[v11-develop] Documentation moved from frappe and erpnext

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:

51

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 :slight_smile:

We’d appreciate feedback on this.

27 Likes

Would this slow down the in app help available? Hope any impact to this has been considered.

2 Likes

frappe_io and foundation apps will be installed with frappe and erpnext, so in-app help should work as it is!

@pratu16x7 we need to write a patch for existing installs that will install in-app help.

3 Likes

Thanks for the writeup!

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.

1 Like

Is erpnext docs moved into https://github.com/erpnext/foundation app?

foundation app has several hooks related to website. So what happen if someone want erpnext doc but not foundation website

You don’t need to install the app on any site, it just needs to be there for the docs!

2 Likes

Also interested in the correct methodology for making documentation changes.

1 Like

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. :muscle:t2:

We should call it ERPNext Documentation³

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.

Avoids duplication. Also fewer repos mean fewer places to track issues and pull requests!

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 github.com/erpnext - 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.

That seems reasonable.

1 Like