Hi Brian what is frustrating is that this project is extremely strong and the documentation is extensive. However it has been generated in a very lean and robotic fashion without properly considering the audience, and is written from a very privilaged perspective of someone who presumably understands exactly why certain commands are run and what the consequences of doing this / not doing this / doing it wrong are (and obviously the inevitable errors that are spat out are not for the faint hearted and the troubleshooting guide is non exiistent as far as im aware). I take all your points above although it strikes me that it isnt a limitation of able / willing resource to undertake the documenation but a cultural issue - either through arogance or neglect, a choice has been made to omit in depth explanation⌠i tried to make this point earlier today and the moderators canceled the post and sent me some political correctness guide - im an enthusiast of irony so this is gratefully received!
and to be clear on the irony point - the moderators sanctioning someone who points out deficiencies in documentation whilst in a thread which has a title that itself insinuates a poor quality of documentation, is not an encouraging sign!.. and to then send the detractor some BS regarding threatening and abusive behaviour is comical⌠no doubt this is similar to the algorithm used to thoughtfully generate documentation
@alpresidente while you have explained a lot, where is an example that others can use to follow? Or, for that matter, if you have already some good documentation done then can be used as an example.
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âŚ
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!
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?
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!
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
