ERPNext Conference 2019* ERPNext.com Blog

Do you also think the documentations are not well written?


#1

Okay, now i got your attention!!

Here is what you can do:

  1. Give us some examples of what you have seen as the best documentation to emulate and get inspired by

  2. Give specific suggestions / corrections / grammar mistakes / outdated / references

good feedback : “xyz page leaves out explanation abc fields”

useless feedback : “documentation is not so good”

  1. Provide fixes and post it. [make a post on the forum] saying : this page should read like this. Yes, give us the small suggestions you want to see

  2. Ask clarifying question about the docs. When you find the clarification, post the suggestion here.

In the mean time, the module for documentation well find leaders, editors and contributors.

Look at volunteering. It is rewarding.

Cheers

Continuing the discussion from List of module volunteers:


Making Changes in Payroll
#2

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 .


#3

What a well put challenge Not_a_countant!

What’s a whiner or ingrate to do :wink:

“Look at volunteering. It is rewarding.”

Yup to contribute back is arguably more productive, sustaining and gratifying.


#4

I agree on this! I have already begun working on my little niche!

ERPNext video tutorials in spanish

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:

  1. 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.

  2. Translate the entire english documentation to spanish

  3. 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.


#5

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


#6

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.


#7

More to come soon, including videos!


#8

Tip-top!! :slight_smile:
Can we speak and coordinate efforts? My initial thinking:

  1. merge official, you docs
  2. translate afterward

Else the fidelity is a bit lost, if you don’t mind! Cheers
Deepak


#9

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!


#10

The work flow exists but the work is not flowing. :slight_smile: 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.


#11

I am sorry, I do not understand what you mean.


#12

Next logical Question:

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.

BKM

BKM


#13

Good points and questions :slight_smile:

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 :slight_smile: 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. :slight_smile:


#14

meaning : process exists in the official docs. just no one is using it.

We will see how we can merge and address the questions from bkm as well.


#15

Hi All,

How about this as a model to emulate? Looking for your comments.

@Muzzy, @bkm , @Obinna_Ukwueze
Since we are part of the module volunteers, I am tagging you :slight_smile:

A few of things I like about it :

  • Familiar structure to reading a book
  • Modules and Chapters
  • Discussion attached to each topic, so you can clarify "right here right now"
  • ERPNext themed (they use Frappe and ERPNext in bits and pieces)

If you guys feel it is ok, we can do it.

Thanks


#16

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.

BKM


#17

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. :slight_smile:

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.

Let me know what you think!


#18

See that? That is why I like your ideas. :star_struck:

BKM