Hi aakvatech - i actually posted an example and the moderators removed it (lol) but i will repeat and look to engage as helpfully as possible so bear with me. The example i gave was that there is a bench command to set the default site - it clearly explains how to run the command. What it fails to do is explain exactly what a default site is and why i would want one and what the consequences of me having one or not having one are… and troubleshooting possible issues in this sphere. I could easily go through all the documentation and ask similar contextual questions and not find the answers there… This is why i am making the point that it seems like a cultural approach to documentation that in my view is wrong (although im also happy to accept that im mentally deficient and need to be better at processing docs of this type)
We don’t have the power to change this project’s people, or change its culture. Frappe/ERPNext began in 2008. It’s very well-established at this point. The leadership team has its policies, workflows, and ways of doing things. Sometimes we’ll agree with them. Sometimes we won’t.
I generally agree with you, and share your concerns.
However. When writing posts like this, my friendly advice is to conclude by offering Ideas & Suggestions for improvement. You have explained why you feel the documentation is substandard. Can you offer ideas or solutions to this problem?
If you cannot, then some people (including some moderators) are going to interpret your post as a pure “rant” post. Or a personal attack on the maintainers.
point taken Brian, although people choosing to categorise constructive criticism as a personal attack or a rant is a limitation im unlikely to influence
Moving on from that, my suggestions are as follows, noting that they are cultural “aproaches” and not technical points.
If i was documenting this product or anything else for that matter I would ask a set of questions regarding the audience that was looking to consume the documentation and the outcomes they were looking to achieve. If im making assumptions about their capabilities i would state these (and perhaps even offer pointers to where they could address these gaps and bootstrap themselves to the privilaged view point i now have as i embark on the documentation)
Moving on from that scene setting i would look to produce a comprehensive directory of the functions, commands and capabilities of the product much as the folks here have done
…yawn! ok now to the bit that i think is missing. Within the structure of the entire documentation i would ensure the reader knows WHY they are running a certain command or undertaking a task. Regurgitating the command syntax etc has its very important place, and may in fact be adequate for a distinct standalone and largely self explanatory utility like gunzip for instance, but for a suite of interdependant software components it is important to allow the user to see into the black box and understand what the consequences of the command they are running are
As the expert, if i ask and answer questions like the ones below i will have gone a long way to help the user understand and use my product (there are likley many more questions but they are intended to probe the surrounding context and likely questions the user has at this juncture - its a “theory of mind” type exercise which brings me uncomfortably close to the autism spectrum, which i was determined to avoid)
Why am I running this command?
What components does running this command affect?
What does success and failure look like?
How do i diagnose a failure?
When should i and shouldnt i run the command?
Are there alternative routes to the same outcome? (pros/cons)
A weird consequence of writing docs in this fashion is that users will be granted a look into the black box and will gain a robust understanding of the product - and who knows some of these people may turn out to be competent and thoughtful documenters!
What you want is nicely elaborated here. Thank you for the efforts.
Your insight in documentation seems to be elaborate. Would you be able to start a working group on telegram and lead a group with specific documentation target areas and fix them on a separate wiki site which can be used as reference as and when required?
I agree that most of the docs are terse and can be only understood by people who already know the topic well. I have found that to be true of SAP , D365, React, Vue etc etc…It is almost like docs are not written for newbies but just to serve as a remider for those who already know their stuff.
But no one else is contributing (including me) And there in is the problem.
Mary Douglas once wrote, “those who receive gifts despise the giver”. There’s probably no place better to see it than open source.
The irony of this thread, risen from the dead four years on, is how much actual change seems to have gone completely unnoticed, even by old timers. Four years ago, the documentation was almost non-existent. Now, it’s terse and far from perfect, but it’s a tremendous resource. The thing about that resource: It was a gift. There’s no money to be made writing documentation. It’s hard, slow, tedious, thankless work. After pouring hundreds of hours into it, people will still tell you how disappointed they are that you haven’t done better.
The ball is in your court @alpresidente. You have a clear vision for what you think good documentation should look like. Will you actually do something about it? We’ll see.
Hi Peter I have been careful to compliment what i think is in many ways an excellent project (noting that my opinion is of minor value!) - but that said I have no intent to kiss ass over things that I think could be masively improved. Ive also taken time to critically explain how i think the improvements could be made - if you lift your visor for a moment, you will notice that the things ive mentioned are not things I can directly influence because i dont have the expertise necessary to write documentation for a product i do not have expertise in
So with the above in mind, and ignoring a clumsy effort to guilt me into silence, please feel free to engage me and any other consumer of the docs thoughtfully on how they can be improved
This is the only viable solution, in my opinion. I just wouldn’t use Telegram. We’ve been down that road before.
We had a Documentation “working group” on Telegram maybe 4-5 years ago. There was no plan, no leadership team, no rules. Just a bunch of people chatting, giving their opinions. It quickly degenerated. We spent weeks arguing about what platform to host the documentation on. I don’t think the group survived past that initial argument. Ultimately, everyone agreed to disagree. And just kept on doing their own thing.
Same as today.
To finally break this never-ending cycle of Documentation Deadlock, here’s what needs to happen (imho)
- A real, professional Working Group. With well-defined rules and policies. With mechanisms to break-up stalemates, and keep progressing.
- Regular scheduled meetings, note-taking, and publishing those meeting notes publicly.
- Leadership documented, so everyone knows who’s organizing things.
- Ways to communicate with these leaders, without emailing each directly or spamming them.
- Leaders from a diverse set of backgrounds and interests (not just full-stack developers, or consultants, or organization CEOs)
- Ways for all participants of the Working Group to feel valued, and that their opinion is heard. So it’s not just Leadership Team doing whatever they want, and ignoring everyone else.
- An independent documentation website, owned and maintained by the Working Group. With no single human having sole ownership and control.
- An inclusive communications tool, that doesn’t require people to own phone numbers, or live in certain countries, etc. These forums are a good example. Telegram and Discord are bad examples.
Bonus: -If- the above was successful, what you’d have is the foundation and framework for a future, worldwide User’s Group. Something several of us dreamed about, during the days of the so-called ERPNext Foundation.
sounds like a good plan there Brian - in project management terminology i think youve just described a Terms of Reference and given a very good case for having one! (Terms of reference - Wikipedia). Applying some form of project management methodology could [help] break through the deadlocks you decribed also…
I hadn’t heard that phrase/terminology before. Thank you! 
you should consider yourself lucky to have avoided such a thing!.. jokes aside, producing such a document can be a powerful tool to keep things on track - its not set in stone and should be revised as the project matures. My sense of such a document is it should be considered the thing you produce to show you have some idea what the hell you intend to achieve, the what, how, who questions… ironically the kind of questions i have already alluded to!
Something I’d like to know…
Are there companies that have been profiting from ERPNext? I don’t mean covering payroll and hoping for the best. I mean Lambo money.
If so, those CEOs and CTOs are not likely in this forum, but their dev and consulting staff are, presumably.
I would think it is greatly in their interest to keep ERPNext growing and competing in the ERP jungle. I would think they’d realize that poor documentation puts severe drag on a project. Am I wrong?
Anyway, you can probably see where I am going with this. My work with ERPNext has been entirely about keeping one small business competitive. I’m a cost centre with intangible value. Us diving into a documentation project … just ain’t gonna happen.
When you look at documentation of projects like NodeJS, npm, Python, etc, etc, am I supposed to believe it’s all done by sole proprietors volunteering a couple of hours every weekend?
I suspect that my situation is exactly the typical ERPNext demographic. Does that demographic represent 100% of ERPNext stakeholders? Surely somebody, somewhere is doing more, and even much more, no? Has the community ever been surveyed?
So, can I humbly ask the Lambo drivers to raise their hands and volunteer to pony up for a real documentation project, and actually pay people to do it properly?
Or am I being naïve?
suspect a little naive Martin - there is no obligation for users of open source to pay to access the code. That said there are often commercial operations running in parallel giving “support / availability” guarantees. The implication being that if your org is “important” eneough to care about you would likely pay the commercial arm of the project to ensure your system has some availability. The interactions between the community and commercial arms will vary by project. There is clearly an insentive for community and commercial arms to improve their documentation because its necessary to grow the fan base… good luck encouraging donations!
I guess I was too coy and indirect.
How about this:
If there are companies solidly profiting from ERPNext and giving nothing back … don’t they deserve to be publicly named, shamed and pressured to feed and care for the beast of burden they’re riding?
only if your intention is turn an open source into a tyrany directed by those best equiped to exert pressure and bring shame upon whoever they choose… the sentiment you express is valid - i.e. why should people get shit for free, but your proposed execution is at complete odds with the fabric of open source… The open source approach is not water tight to the direct acountability you crave but its benefits outweigh this
i would suggest you get the clarity you require be googling “open source” or failing that stroll into an S&M club and complain about nudity
“tyranny” ???
“nudity” ???
I’d like to point out that I have been writing software since 1979. I have used open source software exclusively since 1995. In 1999, I wrote the first 100% open source government to business service in Latin America, using RedHat, Apache, MySql, Java Servlets and a thing a bit like Ajax that I invented myself to provide performant access over 28.8kbps modems.
I’d also like to point out, that if you have a look, I have contributed a quite significant number of posts in this forum that deliver clear explanations of issues the official documentation has never covered. A few examples :-
I’m very curious to understand why you think lambo drivers owe you that.
thats good to know Martin, although it makes your question no less suprising 
I think this thread has run its course, and is just digressing now.
Feel free to open a new thread, if you have any ideas for a path forward, solutions, etc.