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.

Living test documentation

I’ve read these slides by Cyril Martraire. So I got pedantic (a custom on Twitter) and wrote:

.@cyriux just read Living Documentation Jumpstart slides http://t.co/PmNcFM8nyn. I do that too for specific API doc or test reports ;-)

— Romain Touzé (@romaintouze) June 24, 2015

So what am I talking about? For now, I’ll take the example of testing because it was quick and pleasant to do.

This particular project was to build load and transform processes to store call data reports in a data warehouse. The transform processes where written in PLSQL as they were embedded in an Oracle database.

They were pure batch processing so the testing could be easily automated. That’s what we did, using the following approach:

• Tests are implemented in Java, because it’s a widely known language, accessing Oracle DB is easy with OJDBC, and testing environment is easily setup thanks to Maven (if you don’t believe me, try to connect Oracle with PHP on Linux…).
• The whole context is inserted in the database on test setup. The conext and the results are deleted on test teardown.
• The stored procedures are launched in the test cases and assertions are run on the results retrieved with SQL queries.

Unfortunately, we did not propose these test suites as a deliverable to our client. Rather than that, we committed to provide a (manual) test result report, extracted from Quality Center. Boring. So the idea was: “why not generate test steps descriptions so that they can be run manually”.

This was easy because this kind of test were made of a repeatable pattern:

Given a GPRS call report
When the field XXX has value YYY and ZZZ field has value ABC
Then the corresponding field in table BBB has value CCC

So I associate the patterns with methods to which I pass the test input and outcome has parameters:

public void checkBBBResultsDependingOnXXXandZZZ(YYY, ABC, CCC) { … }

The test file was clean. The test where automated and it was easy to parse the source code to translate the tests. I did that in two parts.

First, I extract the delete and insert queries to put them in an initialisation part of my documented test case.

Then I parse my test class to extract calls to method checkBBBResultsDependingOnXXXandZZZ and their parameters to translate them in non developer language (French in that situation).

Translation scripts where made in Python. They were stored in VCS along with the Java test cases. They produce a result in plain text that I used to copy and paste in quality center. Then I manually declared that the whole campaigns were passing. The software is smart enough to generate a test report as a MS Word file from the campaigns results.

Remarks:

• I think I could have automated the insertion in quality center. The API looked complex though and wanted to be able to check what I was doing step by step in the copy and paste sessiosn.
• I’m pretty sure the client did not look at the tests afterward (who could read these boring reports anyway?). They were just in case to prove that we did test the application, and to be able to reproduce the test suits if needed. Therfore I’m glad not to have spent to much time on it.

Conclusion:

People talk often about BDD, using Gherkin syntax and so on. Sometimes its improductive, because you have no access to the business people, you add a translation layer that is a potential source of error and that is long to setup.

Generate your QA test cases from the souce code is the opposite and can be an alternative if you have no real access to the business, if the business cases are simple to explain and to automate. Finally, it allows the busniess prople to check that our implementation is correct with a language they can understand.

Manuel d'installation

Au boulot, le dernière livraison majeure que j'ai faite était plutôt tranquile, merci les pratiques agiles et l'intégration continue. J'ai pu me concentrer sur l'élément de documentation le plus important : le manuel d'installtion. En effet, vous pouvez livrer le meilleur soft du monde, si l'installation est hasardeuse, votre travail sera tout de suite regardé d'un mauvais œil.

Dans mon jeune temps, je pensais que les personnes qui installaient les softs étaient des informaticiens cheuvronnés. Des gens qui savent éditer un fichier avec VI, chercher les informations de configuration sur le système et la base dedonnées et lancer des scripts shell. Grossière erreur :

• Parfois, la qualification est réalisée par des équipes spécialisées, on parle de Tierce Recette Applicative (TRA). Il ne faut pas penser que ces équipes sont faites de geeks développeurs hardcore. Les personnes de ce genre sont embauchées pout faire du développement ! D'un autre côté, pour faire de la recette, il vaut mieux embaucher des gens avec des connaissances métier, non ?


• D'autres fois, les équipes qui installent ne font que ça tous les jours (j'en ai vu). Je ne pense pas que ces gens, mêmes s'ils sont très compétents, aient envie de se taper des dizaines de fichiers de configuration pour installer un soft. La solution livrée est censée être intégrée, non ?

D'un autre côté, lorsque la procédure d'installation est fastidieuse, il est d'autant plus complexe de la documenter de façon satisfaisante. Comme c'est quelque chose de maîtrisé par l'équipe de développement, on a facilement tendance à oublier des étapes...

Alors, voilà mon parti pris: améliorer l'intégration de la procédure d'installation, que ce soit en terme logiciel et documentaire. Idéalement, l'installation d'un logiciel doit pouvoir se faire depuis une seule machine en ne tapant qu'une commande, sans éditer de fichier. Mon manuel d'install est light, il n'expose que les prérequis logiciel, dit ou doivent être déposé les archives et donne LA commande à lancer. Les paramètres de l'environnement de prod sont dans des champs du document qui sont mis à jour par une macro. Perte de temps minimal pour la mise à jour.

Je n'ai même pas été contacté pour faire une assistance à la mise en production.