Documentation has to be one of the most boring subjects you can think of?


“Documentation has to be one of the most boring subjects you can think of” [1]. This is not a reason to do not deliver a great documentation, online PDF’s, contextual information, videos!

Keep writing documentation is a long journey because changes in the solution imply an update of the documentation: Web, PDF’s, ePub, Videos to say the least.

StratEx proposes (1) a contextual documentation accessible while using the web application, (2) an html documentation in English [11], (3) a PDF version [12] and (4) an ePub version but issues occur due to the embedding of the Videos [13]

 

Take a look at the documentation before reading the rest of the post: http://stratexapp-docs.readthedocs.org

 

What are the needs?

Before starting to write the documentation we wanted it to be:

  1. Easy to update
  2. Raw text necessitates a simple text file editor such as vi, notepad or TextEdit
  3. Keep trace of the versions
  4. Spelling and Grammar check
  5. Generate several outputs like HTML and PDF
  6. Support binary file formats such as videos, images
  7. Web view would run offline, more precisely without the need of web server
  8. Run on our local computers

 

We have found our champion besides the fact that it didn’t address the requirement #4 “Spelling and Grammar check”. We still use Microsoft Word to check simple misspellings or grammar errors.

 

What are the solutions?

They are many solutions out there such as Wikis, Document Management Systems or custom made software’s. None of them addressed the needs for our rather small organization.

We develop our software using Microsoft Solutions and we didn’t want to develop custom made software, as it was not our core business.

We looked at Zen Desk [2], User Voice [3], Transifex [4] and many others.

Either the costs were too high for our small organization or the solution were too complex for the moment but they are good chances that we will use one of them in the future.

What is our choice?

We decided to use several solutions:

  1. Sphinx “the python documentation generator” [5]
  2. Read the docs, “Create, host, and browse documentation” [6]
  3. Microsoft Word for its Spelling and Grammar check  [7]
  4. SublimeText [8] as a TextEditor including syntax highlight for the RestructuredFile format [9]
  5. BitBucket [13] as file server to host the documentation

 

Use the StratEx documentation as a template?

Are you interested to use the StratEx documentation [10] as an example to design your documentation, feel free to do it!

You can easily copy our documentation and adapt it to your needs. We have used most of the features of the

 

The documentation maturity model

Before writing this post we didn’t know that a maturity model for documentation exist [15] (see the figure).

Based on the reading [16] we may be surprised that we reach the “Strategic Level” of this maturity model; indeed:

  1. Level 1: Ad Hoc: We do propose FAQ’s through User Voice [18]
  2. Level 2: Basic: PDF files are posted online [12]
  3. Level 3: Organized:
    1. Static HTML are posted online [11]
    2. The documentation can be localized by country (next version of the StratEx documentation) [5]
    3. Has an organized table of contents [11]
  4. Level 4: Strategic:
    1. Single Sourcing through BitBucket [13]
    2. Collaborative authoring including community content [13]
    3. Search that is contextual and adapts over time [5]
    4. Documentation Content Analytics by using Google Analytics [17]
  5. Level 5: Social:
    1. Combines elements of Level 4 with community touch upon User Voice [18] and BitBucket [10] but this isn’t our strong advantage yet
    2. Learning communities that include documentation and Knowledge Bases through User Voice [18] but this isn’t a strong point neither
  6. Level 6: Intelligent:
    1. Marked by content that is personalized for each user (not planned for StratEx)
    2. Personalized search (not planned for StratEx)
    3. Location based mobile documentation  (not planned for StratEx)

 

Conclusion

We have listed the technologies that, brought together, have reduced drastically the workload to support the production of text documentation.

The solution is a mix of open source software, Software as a Service [19] solutions and software engineering methods to deliver easily a documentation that may be enjoyable to read.

Today, the solution came at no cost besides the human factor but it will change as soon as more users will use StratEx and more collaborators are hired.

It took us 70 (wo)man/hours to build the documentation you can read in HTML, PDF or ePub: http://stratexapp-docs.readthedocs.org

There is still a lot to improve: the PDF pictures are not correctly sized and the ePub does not display correctly the Videos; besides that we didn’t feel hard to move from our Microsoft Word documentation to the Restructured File Format [9] which is used in any documentation written by a Python developer

 

By now, your colleagues shouldn’t have a good reason to write the documentation when you see its result!

 

Links

[1] http://docs.bluemangolearning.com/m/docs-that-rock/l/55080-why-documentation-matters Why documentation matters

[2] https://www.zendesk.com Zendesk.com | Customer Service Software | Support Ticket System

[3] https://www.uservoice.com UserVoice integrates easy-to-use feedback, helpdesk, and knowledge base management tools in one platform that empowers users to speak and companies to understand.

[4] https://www.transifex.com Localization platform for web apps, mobile apps, websites

[5] http://sphinx-doc.org Python documentation generator

[6] https://readthedocs.org Read the Docs, Create, host, and browse documentation

[7] http://products.office.com/en-us/word Document and Word Processing Software

[8] http://www.sublimetext.com Sublime Text is a sophisticated text editor for code, markup and prose.

[9] http://docutils.sourceforge.net/docs/ref/rst/introduction.html reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system.

[10] https://bitbucket.org/altf1be/stratexapp-docs Raw documentation of StratEx, the easy to use, Web Project Tracking Automation tool that brings focused collaboration between business, consultancy and software development teams.

[11] http://stratexapp-docs.readthedocs.org HTML version of the StratEx Documentation

[12] https://media.readthedocs.org/pdf/stratexapp-docs/latest/stratexapp-docs.pdf PDF version of the StratEx documentation

[13] https://bitbucket.org Free source code hosting for Git and Mercurial by Bitbucket

[14] https://readthedocs.org/projects/stratexapp-docs/downloads/epub/latest/ ePub version of the StratEx documentation

[15] http://dl.acm.org/citation.cfm?id=170869&dl=ACM&coll=DL&CFID=592512625&CFTOKEN=53062926 Software system documentation process maturity model

[16] http://www.cloudave.com/6521/the-documentation-maturity-model-infographic/ The Documentation Maturity Model (info graphic) By Mark Fidelman on October 13, 2010

[17] https://analytics.google.com Web Analytics & Reporting

[18] https://stratexapp.uservoice.com StratEx Easy-to-use feedback, helpdesk, and knowledge base management tools

[19] http://en.wikipedia.org/wiki/Software_as_a_service “Software as a Service is a software licensing and delivery model in which software is licensed on a subscription basis and is centrally hosted”

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: