If you see the documentation lacking in a particular area of interest, but do not have the operational knowledge to fill in the missing information, then how do you propose that gap gets filled?
I have seen several areas of documentation where there is just not enough information to make a subject work, but at the same time I have no idea how to use the part of the system that I needed to be documented.
It’s like a catch-22. I don’t know how to use a part of the system, and I find the documentation for that part of the system is deficient. How does one proceed from that perspective?
You don’t want to be critical of the efforts, so you don’t say anything and the subject remains without good documentation.
If there were a team devoted to documentation, then there would at least be a place to log the area of concern. Otherwise I believe it gets lost. Is there a team devoted to documentation? If not then how do you propose we capture the concerns of users, that may not be able to really create the missing subjects due to lack of knowledge in a part of the system?
I believe your effort to increase the completeness and accuracy of the documentation is a very noble cause, I would just like to know if you have any ideas around capturing and prioritizing the documentation tasks?
I even like doing documentation. I do as many Step-byStep guides as I can and post them here as it is now. If I knew how to use the areas of the system that might be behind in the documentation department, then I would write those docs. Currently I use the many hours of trial and error to figure out how something works and then I document it. Is there a better way when it comes to documenting the user interface permutations of ERPNext modules?
Just curious. I would like to help. I am just afraid that my current brute force, trial and error method is not good enough for the task.
Was planning to “curate” the info found on the forum. [quote=“bkm, post:12, topic:36623”]
If there were a team devoted to documentation, then there would at least be a place to log the area of concern. Otherwise I believe it gets lost. Is there a team devoted to documentation? If not then how do you propose we capture the concerns of users, that may not be able to really create the missing subjects due to lack of knowledge in a part of the system?
[/quote]
Was also a question during the call. where to log the question. The last time i logged a question in the docs and sent a PR, it got rejected so lack of interaction at the docs level is not helping it evolve.
Suggestions? Go for a media wiki? [quote=“bkm, post:12, topic:36623”]
Just curious. I would like to help. I am just afraid that my current brute force, trial and error method is not good enough for the task.
[/quote]
What you are doing is really great. In the end you guides are from practice. Documentation is a little theoretical/ conceptual at times. Keep up the good work.
Okay… I have had a day or two to read your example and digest it a bit. Now, I am “not-an-accountant” and “not-investor-savy” but I am pretty god at judging documentation.
The documentation itself is laid out nicely and it does read quite easily. My concern is the “Discussion” part. From my read thru everything, the “discussion” function appears to be mainly about the accuracy of the leading document, but the corrections in the discussion do not appear to be moved to the actual documentation portion of the structure even after lengthy periods of time.
This “time lag” makes me think the discussion portion may just be a lazy mans way of adding confusion to the document project. By having all of the corrective comments right there, those responsible for keeping the actual document updated get a free pass to ignore the effort because a reader could just keep reading into the comments to get the corrections.
To me, this makes what should be a concise set of documents into a never ending and ever expanding nightmare. A user would have to read 4 to 5 times the number of pages and then sort out the good advice from the bad on their own.
After doing my best to find positives in this example, all I came away with was frustration.
But let’s NOT throw away the whole idea…
Another version of this where the comments related to a particular chapter (for corrections and additions) could be “Linked” to the chapter might be better. Each chapter would need to have it’s own category in the “Documentation Forum” so as to keep it easier to manage, but then the individual corrective topics could be easily searched and tagged (similar to github) when corrections are added back into the primary online documents. Something like that might work better.
The example model that I forced myself to try out for you, just seems quite the mess. There would need to be a better approach. My suggestion is probably only one of many possible fixes, but I would bet that my observation and analysis of the example is pretty close to what others might have to say about it.
@Not_a_countant … Than you so much for keeping the conversation alive.
Thanks for this! I think the curator has a job to do there and you can see he is falling behind. But, atleast there is a discussion attached to it. So I see it as a positive.
In any case, pls. check this post out asking for new designs.
I have proposed a structure that breaks “documentation” into 4 categories. One size fits all doesn’t work.
One extra advantage of it is, people can say, I love this but I hate that. Right now, we tend to paint the entire docs as bad but cant seem to put a finger on it.
i would like to say that the documentation of this project is 100% excellent - every aspect of it is sweet perfection (its disspointing that anything more challenging than this comment isnt tollerated by your moderators lol)
lets see if this gets past the moderators lol… there is a lack of focus on troubleshooting (almost none). Documentation states commands with some very terse explanation of what the command does. There is generally no context given - for instance why is the command run, when is it run, what happens if it isnt run - these are all the sort of perspectives that assist the user troubleshoot when things go wrong (which they often do)
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
