Closing The Documentation Loop

Fixing our Achilles Heels: Documentation!

 · 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!

Rushabh Mehta

Rushabh is a software developer and founder of ERPNext. He usually writes about the startup experience, open source and the technologies he is working on.

1 comment
lxnow August 7, 2013

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

Add Comment