Hi All, thanks for your comments and interests on this topic.
After looking at different tools and examples such as readthedocs, crisp, media wiki, git, python, zerodha, markdowns, intercom, wikihow, google docs and my life time experience in making presentations :
Contribution to perception
80% appearance : of how documentation is perceived is appearance (structure, colors, readability, consistency, spelling, grammar (more forgiving)), lack of segregation of topics
20% content : whether it is outdated, old versions, incomplete, lack of depths.
So if you ask me what is wrong with ERPNext docs is there is
- No differentiation of topics (functional, programming, configuration, usage, customization).
- Feels like almost everything is thrown is or is widely scattered.
- There is no strategy behind it. Basically it has evolved into its own being.
Generally one would feel frustrated with it and hence the constant noise of “documentation is not so good”.
What people are saying is, this could be perhaps better.
Simply put, a level of consolidation & refactoring that should have happened, hasn’t happened.
In other words, too much there is no one with enough energy to carefully curate it.
So here is my proposal and if there is not a violent opposition to it :
I propose to break the entire “documentation” into 4 parts
- Beautiful User Documentation (strictly no code) // Zerodha style
- Configuration & Settings // Zerodha style
- Customization (with code) // GitHub Wiki, Markdowns
- DevOps // Wiki, WikiHow
Now each of this needs a OWNER, who will have authority delegated to him/her to make decisions and take it forward.
Anyone opposes this? Any volunteers?
Thanks