So until now, we had been maintaining the documentation for ERPNext on the source repo (which also served to build the in-app help) as well as the Foundation website to host them. These needed to be kept in sync weekly for any updates from the main repo. That may not be too bad, but we realized that over time, the docs on the ERPNext repo had caused a bloat (due to the docs image blobs for the most part) that suggested perhaps they need management at a place separate from the codebase. So we’ve decided to now host them solely on erpnext.org itself, and remove them from the ERPNext repo.
For example, here are the relative zip download sizes of develop and master post the docs migration:
That’s a decrease by an order of magnitude.
Similarly, for consistency, the docs for Frappe are now hosted on frappe.io, as all our other related projects.
This certainly helps with the separation of concerns. However, this means contributors will have to now, in turn, have to make two different PRs for a feature, with a separate PR on the foundation/frappe.io repository to update the docs. This certainly is unintuitive, but in the case of elaborate documentation, it isn’t uncommon for projects to have a separate repository to maintain them. I guess we’ll have to start somewhere
I’m assuming the only way to test documentation changes now is to basically install the documentation app into your site and make changes, right? Documentation for that would also be appreciated.
Found some documentation on how to create documentation for custom app here, and it seems to have been updated to reflect these recent changes. Thanks! I like the idea of it being a “custom app” so that installation of documentation is only one line command, and that it is separate to reduce the size when installing.
I second @tmatteson and @vjFaLk motions on creating proper documentation to make documentation changes. Especially now that we are re-working Agri-next.
A more flexible way to enforce separation of concerns would be to have a dedicated documentation repo(s) rather than integrating it with the website repos. I’m not seeing a really great reason the repos should be integrated.
It’s extremely unlikely someone is going to be updating the websites when making erpnext/frappe pulls for features and documentation. This doesn’t increase duplication in that sense.
In this proposal, Frappe Documentation is in the frappe_io repo. the frappe_io repo is a Frappe Pvt. Ltd. website rather than a Foundation website. That doesn’t seem to be the best path forward because it mixes concerns - at some point of time, it’s going to have to be split.
Two dedicated repos for documentation in ERPNext · GitHub - one for frappe and one for erpnext seem to best separate concerns.
I can see how it could be more work to maintain because “documentation” is a website. But maybe that’s an issue better solved with how the documentation is stored and presented rather than merging the website and doc repo.
(Please don’t misinterpret this comment as implying that Frappe has any nefarious plans. I’m just providing feedback.)
Frappe is also the name of the framework and it does not have its own site. Just like how erpnext.org doubles up as both erpnext and foundation site, so does frappe.io
I agree there could be a better model, when there are more resources (developers, contributors) we can think of cleaner separation.
