Improving Docs

[asieftejani]

Hello @DanielRadlAMR
I am continuing our discussion found at #1640
I have some free time now so what would be the first priority

1. Adapting the frappe/erpnext ARM setup to link to the right place
2. Go through the new README docs(readme): refactor readme to explaining how to navigate this repo… #1779

[DanielRadlAMR]

Hey, great to hear that you have the time and motivation to contribute! 🙂

Updating the README in frappe/erpnext is definitely something that should be done soon. However, rather than just fixing a single link, I’d suggest reworking the whole section a bit to better align with our new README. Basically, you could copy the entire “Try on your environment” chapter and replace the “Self-Hosted” section with it — or structure it in whatever way you think is most straightforward for new beginners.

Keep in mind that PRs in the other Frappe repositories are much more strict than here. You’ll need to follow the correct templates (commit messages, etc.). If you open a PR, feel free to tag me — I’ll be happy to give it a 👍

Apart from that, there are definitely many other things that could be improved. Since this is open source, you’re free to work on whatever interests you most 🙂 If you don’t already have a topic in mind, it would be great if you could look through the open issues and see where you can help. If you’re looking for something “bigger,” working on the docs is always an option — there’s plenty of room for improvement there as well. Just note that documentation work usually isn’t a quick win and requires a bit more effort to make a meaningful contribution.

[asieftejani]

@DanielRadlAMR - can you please check my changes on asieftejani/docs-erpnext_docker-update@354de1c and let me know if its okay
@revant it would be great for your input as I think you may need to convince your ERPNext team mates to approve it once its ready

[adithyaappu]

I am planning to continue on #1760 after this week. Happy to help in any way possible. Today I spent the entire day pouring through docs to solve a custom app setup. It really needs some rework.

[asieftejani]

@adithyaappu that would be great 👍

[DanielRadlAMR]

@asieftejani looking good! One more thing: I’d add a sentence at the very beginning that links to this repo and explains that all documentation lives here, and that the setup below is just a snippet from this repository.

I also think you can open this PR without Revant’s approval. In the worst case, they don’t accept it and we can still figure it out with Revant’s help.

[asieftejani]

@DanielRadlAMR
frappe/erpnext#51903
Its now waiting approval - lets see

[Rocket-Quack]

I don't know if I'm alone in this, but I think the commit for the docs is very good, only the .development folder causes me some problems. Please don't misunderstand me, I'll try to explain :)

ERPNext is a Frappe app. In my opinion we shouldn’t ship and maintain a Docker environment inside an app. The reference for Docker-based setups is frappe_docker (This Repo), and I think this repo should primarily point to that rather than embedding Compose/devcontainer definitions there.

My worries are that this will increases the maintenance effort, but also creates more overhead for adjustments during updates later on.

If it should still be included, or if people disagree with me, I would be more in favor of a setup like the one in this Docker repo with a devcontainer-example folder, which then has to be copied manually in order to make adjustments.

TLDR: Docs are good, but please do not put Docker/Compose + .development/development in the ERPNext repo, but rather as a reference/template in frappe_docker, otherwise more maintenance :(

[asieftejani]

Sorry about this ... by mistake ... first time :-)
Thanks for bringing it to my attention

[asieftejani]

Hi @Rocket-Quack
I have deleted the mistakes and corrected as per code rabbit recommendations
Can you take a look now if its okay
Thanks

[Rocket-Quack]

No problem, it can happen :)
But in the future, always be careful and double-check the commits you want to make. There's nothing worse than accidentally pushing secrets or keys. ;)

The docs LGTM

[DanielRadlAMR]

@asieftejani hey, sorry for the late response — my time is quite tight at the moment. :)

First of all, thanks for your effort!

The code changes look fine to me — they’re exactly what we discussed earlier.

The reference for Docker-based setups is frappe_docker (this repo), and I think this repo should primarily point to that rather than embedding Compose/devcontainer definitions here.

@Rocket-Quack, I totally agree. In my opinion, all Docker setup docs should be in frappe_docker, and the other Frappe apps should just reference this repo rather than including setup steps themselves.

That said, I get the feeling this might just be my opinion. Many people don’t dig through a lot of information; they just want a step-by-step introduction that works and is easy to find. Having to jump from one repo to another can be a friction point for them.

I still think having a single source of truth is best. I prefer having one clear place with up-to-date documentation rather than multiple scattered docs that may be outdated.

That’s why I suggested adapting the documentation this way. It’s the approach with the least friction I can think of. Basically, it keeps the docs the same but updated, reflects this repo’s README, and makes the link to frappe_docker more prominent. This way, the changes are mostly cosmetic and will likely be accepted faster — removing parts of the README entirely might not be.

---

Now, on the technical aspects of the PR:

Although the code changes look fine, I don’t think this would be merged as-is. There are a few issues (basically the same points I mentioned in your first PR, if you remember them):

• Commit messages: They don’t follow the conventional commit format.

Every commit must follow the specified format to be accepted in the ERPNext repo — they’re not as forgiving as we are here.

• Branch name: You cannot use develop.
  The PR won’t be merged from asieftejani:develop to frappe:develop. You need to create a new branch for your PR.

---

Tip

Use pre-commit — it checks commit messages and code formatting before each commit and can even autofix some issues. This makes it much easier to stay compliant.

[Rocket-Quack]

That said, I get the feeling this might just be my opinion. Many people don’t dig through a lot of information; they just want a step-by-step introduction that works and is easy to find. Having to jump from one repo to another can be a friction point for them.

I agree, and I would suggest a change to the current doc structure: we could create/move examples and step-by-step instructions to a separate folder, perhaps something like 09-examples. In this folder, we can then provide examples for most use cases, as is already done in docs/02-setup/06-setup-examples.md, for example, but with more options and easier to find. In my opinion, this would improve the structure and more people could benefit from it.

[DanielRadlAMR]

Hmm, I get your point, but I’m not sure this is actually the right thing to do. Separating the “theoretical” background from the step-by-step instructions/examples feels a bit off to me.

Even if we’re technically just moving things into another folder, it changes the learning flow. Separating theory and examples makes them feel disconnected, whereas keeping them together frames the example as a direct application of the explanation that comes right before it.

[Rocket-Quack]

My only concern is that we currently have a lot of technical documentation, which is great, and we also have an examples such as docs/02-setup/06-setup-examples.md.
However, for some people, the use case is that if I want to have a docker setup, I want step-by-step instructions and detailed information about each step. In other words, the idea would have been to include an overview with a list in the 09 example.

├─ docs/
│  ├─ [...]
│  ├─ 08-references
│  └─ 09-examples/
│     └─ overview.md
│     └─ production-setup-with-treafik-ssl.md
│     └─ production-setup-with-acme-companion-ssl.md
│     └─ local-production-setup-shared-db.md

If you only want to run the app locally, that would be the perfect setup, always with a note about further customization if desired. Or you want https with traefik, no shared db, etc. However, for someone who I would now call a "normal user", the step-by-step instructions could help here. Based on this principle, we have the most common setup options that are used most frequently. Maybe for an Overview overview.md something like that we could give this Options.

I don't want to tear apart the technical documentation, but rather expand it and give the user the opportunity to decide for themselves. Here would be a setup with a shared database and Traefik, but if you want to take a closer look, there are further options in folder 03 for example.

Unfortunately, I can't think of any other conclusive way to deal with this, for example, if we also offer nginx with acme companion, we could provide documentation without people having to switch between two documents for the overrides and tls-sll setup.

In other words, specify basic structures and provide in-depth information. Divide et impera :)
I realize this is a lot of text :D, but I'm ready for discussion.