Screenshot 2023-10-25 at 10.48.41 PM.png
Closing The Documentation Loop
Fixing our Achilles Heels: Documentation!
image7f7d4e.png

By

Rushabh Mehta

·

Jul, 26 2013

·

3

min read

For developers, documentation is usually painful. The biggest reason, I suppose is the "context" switching that happens while shifting from coding to writing mode. And documentation has its own issues:

  1. It should be available on the web so that users can search.
  2. There has to be user + developer documentation.
  3. It should be easy to make.
  4. It should have screenshots!

Take 1: Blogspot

The very first attempt to document was started by Umair in April 2010 at Blogspot: http://erpnext.blogspot.in/. At that time, we had just started with the erpnext name and we did not have enough documentation tools. So we started with whatever free tool we thought would work best for us - Blogspot. That site got more than 32,000 visits and still manages to get 15 page views a day!

Take 2: The Manual

The blogspot site was good for quickly replying to support queries, but it did not contain enough explanation for users who wanted deeper understanding. So I decided that I should take a break from writing code and I started with the ERPNext Manual sometime in early 2012. After one month of effort - the Manual was created. There was one major problem. I wrote this in Pages and there was no way to make this searchable on the web. Also being in Pages which is a Mac only software it was hard for anyone else to edit it. The manual did help us reduce our support load a bit more but still it was fast getting obsolete.

Take 3: Website

Again we decided that Umair and Prakash would take the responsibility of making the manual and by this time, the website module was getting mature. So they started re-writing the manual in the website and managed to create this version. The problem was again that the approach was more instructions than explanations.

Take 4: Documentation Tool

There was another big hole we had to fill. Developer Documentation. The only time we did developer documentation was way back in 2009-2010 and it was very much outdated. For the documentation, we used Sphinx, the Python standard documentation tool. But there was no way to document Javascript functions and almost 50% ERPNext is in Javascript.

Since January 2013, we started getting a lot of developer interest and we did not have documentation ready to help them customize ERPNext. So we needed a tool to build that too. Finally it struck to me that there must be a better way to generate the documentation. So I started building a new tool. In the new tools, all documentation, user / developer will be built from the repository and it should be very easy to rebuild it.

The new documentation tools handles different types of sources separately. (If you are on your local machine, you login as Administrator and go to "#Form/Documentation Tool" to start the front-end):

  1. Static files (https://github.com/webnotes/erpnext/tree/master/docs) are built from markdown. There is a custom header where you can define the title and the table of contents of that page.
  2. Javascript code is inspected inside the ERPNext application and using some basic parsing we will be identify the function names and arguments.
  3. Python objects are inspected on the server side and passed to the client and masked as javascript objects. The same tools are then used to build the documentation pages.
This means that the code documentation must be built in the browser. That was okay, but still it took almost 30+ seconds to rebuild the entire docs. This was not acceptable for making minor edits to the static files. So I ended up moving part of the documentation generation to server using Jinja Templating.

Finally the issue was of hosting and maintaining versions. We were keen to use GitHub Pages, fast becoming a standard for Open Source projects for hosting our documentation and we also wanted to use the erpnext.org domain. Since the documentation was built in the `public/docs` folder, Anand thought it was a good idea to make it a git repository that will point to the GitHub Pages repository.

And that was it. Now updating documentation takes only a few steps:

  1. Edit the doc files.
  2. Add images / screenshots if any in the public/docs/img folder.
  3. Build the static docs using `lib/wnf.py --docs`.
  4. Add, commit and push to https://github.com/erpnext/erpnext.github.io
Yes thats it.

And heres the output: http://erpnext.org

Not only is it easy to push new documentation but we hope the community can also start participating!

Published by

Rushabh Mehta

on

Jul, 26 2013
1

Share

Add your comment

Success!

Error

Comments

l
lxnow

· 

August 7, 2013

I'm aware of the PDF manual and have it handy, but didn't know there were reference help pages!

Discussion

image7f7d4e.png

Paul Mugambi

·

3 days

ago

Beautiful read, and an insight into an individual I respect and have learned a lot from. Am inspired to trust the process and never give up.

image4c43d6.png

Anna Dane

·

5 days

ago

I must say this is a really amazing post, and for some of my friends who provide Best British Assignment Help, I must recommend this post to them.

Add your comment

Comment