vendredi 25 mars 2016

Documentation workflow

I do that because I use to spend a lot of time struggling with MS Word to get the document and the layout I want. I’m quite happy with the result.

Here are some special tips I use:

rst2html.py come with docutils package in Python. You can install it with pip and it works with Python 2 and Python 3:

pip install docutils

I write documentation in French (mostly), with non ASCII characters. Therefore, every rst files I write uses UTF8 encoding. It can be a problem when you use rst2html.py on Windows with Python 3. Fortunately, you can specify input and output encoding with --input-encoding and --output-encoding optioins.

You have to fix the special characters like apostrophes, quotation marks and hyphens in your text file. To do so, you can use Vim digraphs.

I chose reStructuredText (rst) instead of markdown because it allows more options for layout. Precisely, you have a standard ways to draw tables. I know that AsciiDoc can to the same, but I do not want to learn another syntax.

Vim can do spell checking. Use this command:

:set spell spelllang=(your language)

If you do not have a dictionary installed for your language, Vim will download it for you. Default language is English, of course.

Pandoc is really easy to use. Oh, by the way, it’s written in Haskell:

pandoc -f rst -t docx -o your_doc.docx your_doc.rst

Adapting style in your resulting docx can be done painlessly in most of the cases. Select a paragraph that needs style change and use contextual menu to select every paragraph with the same style. Finally, apply the style you want to the selection.

It is a nerdy way to write project documentation, but it’s the way I like it. I think it helps me to write faster compared to direct MS Word editing.