I always think the documentation for Archlinux is impressive in its absolute completeness …
I have contributed to the docs for ERPNext as using zgithub isn’t so bad even for a non developer like me .
Before we continue moving forward with all our ERPNext wishes, we need to prepare materials for users to study, so they can refer to it when in doubt.
I have set as a goal this year to do the following:
Finish 200 video tutorials in Spanish, emulating original ERPNext videos as close as possible.
For this purpose, I have tasked one staff to help me create video scripts. I also made a “curriculum” that I will gladly furnish as is in this venue in a bit.
Translate the entire english documentation to spanish
Finish documentation, dev, testing for Agriculture module.
Ambitious!
[Added] I believe current documentation is sufficient, and is the best anyone can expect for such a whirlwind of activities around this software, but I do believe we need improved docs / videos to better guide new users, current users. This, of course, results in better marketing.
Great! Keep it up!!
How will you manage if parts of it are outdated or incomplete? Or here is another thought, if you find something wrong with the docs, would you let us know? So we can correct it?
Thanks
How will I manage:
Bear in mind, this is work in progress. I just have the outline and a pair of concepts here and there, but this will be filled. Since it is on GitHub, others can contribute to it! I have actually given a course recently to high school students based on my “Module 1” and “Module 2” in these files.
At some point I would love to merge with official, but needs to be complete and accepted by the community!
I’m doing both at same time: English and Spanish, it just takes 20 more minutes per topic. I have a desperate need for spanish documentation because customers here really benefit from a one-on-one presentation, but I want to re-task myself to developing!
The ideal workflow for something like this is to set up your own git branch. Work on the specific topic: steps to do something. And then commit on your branch and send a pull request!
The work flow exists but the work is not flowing. If it is ok, could we merge it? let me take it up with the module team and see how to work it the best.
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)
