Documentation matters or why OSMC made me write NSClient++ API docs

Last year I learned about the new HTTP API in NSClient++. I stumbled over it in a blog post with some details, but there were no docs. Instant thought “a software without docs is crap, throw it away”. I am a developer myself, and I know how hard it is to put your code and features into the right shape. And I am all for Open Source, so why not read the source code and reverse engineer the features.
I’ve found out many things, and decided to write a blog post about it. I just had no time, and the old NSClient++ documentation was written in ASCIIDoc. A format which isn’t easy to write, and requires a whole lot knowledge to format and generate readable previews. I skipped it, but I eagerly wanted to have API documentation. Not only for me when I want to look into NSClient++ API queries, but also for anyone out there.

Join the conversation

I met Michael at OSMC 2016 again, and we somehow managed to talk about NSClient++. “The development environment is tricky to setup”, I told him, “and I struggle with writing documentation patches in asciidoc.”. We especially talked about the API parts of the documentation I wanted to contribute.
So we made a deal: If I would write documentation for the NSClient++ API, Michael will go for Markdown as documentation format and convert everything else. Michael was way too fast in December and greeted me with shiny Markdown. I wasn’t ready for it, and time goes by. Lately I have been reviewing Jean’s check_nscp_api plugin to finally release it in Icinga 2 v2.7. And so I looked into NSClient++, its API and my longstanding TODO again.
Documentation provides facts and ideally you can walk from top to down, and an API provides so many things to tell. The NSClient API has a bonus: It renders a web interface in your browser too. While thinking about the documentation structure, I could play around with the queries, online configuration and what not.

Write and test documentation

Markdown is a markup language. You’ll not only put static text into it, but also use certain patterns and structures to render it in a beautiful representation, just like HTML.
A common approach to render Markdown is seen on GitHub who enriched the original specification and created “GitHub flavoured Markdown“. You can easily edit the documentation online on GitHub and render a preview. Once work is done, you send a pull request in couple of clicks. Very easy 🙂

If you are planning to write a massive amount of documentation with many images added, a local checkout of the git repository and your favourite editor comes in handy. vim handles markdown syntax highlighting already. If you have seen GitHub’s Atom editor, you probably know it has many plugins and features. One of them is to highlight Markdown syntax and to provide a live preview. If you want to do it in your browser, switch to

NSClient++ uses MKDocs for rendering and building docs. You can start an mkdocs instance locally and test your edits “live”, as you would see them on

Since you always need someone who guides you, the first PR I sent over to Michael was exactly to highlight MKDocs inside the 🙂

Already have a solution in mind?

Open the documentation and enhance it. Fix a typo even and help the developers and community members. Don’t move into blaming the developer, that just makes you feel bad. Don’t just wait until someone else will fix it. Not many people love to write documentation.
I kept writing blog posts and wiki articles as my own documentation for things I found over the years. I once stopped with GitHub and Markdown and decided to push my knowledge upstream. Every time I visit the Grafana module for Icinga Web 2 for example, I can use the docs to copy paste configs. Guess what my first contribution to this community project was? 🙂
I gave my word to Michael, and you’ll see how easy it is to write docs for NSClient++ – PR #4.


Lessions learned

Documentation is different from writing a book or an article in a magazine. Take the Icinga 2 book as an example: It provides many hints, hides unnecessary facts and pushes you into a story about a company and which services to monitor. This is more focussed on the problem the reader will be solving. That does not mean that pure documentation can’t be easy to read, but still it requires more attention and your desire to try things.
You can extend the knowledge from reading documentation by moving into training sessions or workshops. It’s a good feeling when you discuss the things you’ve just learned at, or having a G&T in the evening. A special flow – which I cannot really describe – happens during OSMC workshops and hackathons or at an Icinga Camp near you. I always have the feeling that I’ve solved so many questions in so little time. That’s more than I could ever write into a documentation chapter or into a thread over at 🙂
Still, I love to write and enhance documentation. This is the initial kickoff for any howto, training or workshop which might follow. We’re making our life so much easier when things are not asked five times, but they’re visible and available as URL somewhere. I’d like to encourage everyone out there to feel the same about documentation.


Ever thought about “ah, that is missing” and then forgot to tell anyone? Practice a little and get used to GitHub documentation edits, Atom, vim, MkDocs. Adopt that into your workflow and give something back to your open source project heroes. Marianne is doing great with Icinga 2 documentation already! Once your patch gets merged, that’s pure energy, I tell you 🙂
I’m looking forward to meet Michael at OSMC 2017 again and we will have a G&T together for sure. Oh, Michael, btw – you still need to join your Call for Papers. Could it be something about the API with a link to the newly written docs in the slides please? 🙂
PS: Ask my colleagues here at NETWAYS about customer documentation I keep writing. It simply avoids to explain every little detail in mails, tickets and whatnot. Reduce the stress level and make everyone happy with awesome documentation. That’s my spirit 🙂

Michael Friedrich
Michael Friedrich
Senior Developer

Michael ist seit vielen Jahren Icinga-Entwickler und hat sich Ende 2012 in das Abenteuer NETWAYS gewagt. Ein Umzug von Wien nach Nürnberg mit der Vorliebe, österreichische Köstlichkeiten zu importieren - so mancher Kollege verzweifelt an den süchtig machenden Dragee-Keksi und der Linzer Torte. Oder schlicht am österreichischen Dialekt der gerne mit Thomas im Büro intensiviert wird ("Jo eh."). Wenn sich Michael mal nicht in der Community helfend meldet, arbeitet er am nächsten LEGO-Projekt oder geniesst...

Weekly Snap: Icinga at, Foreman Vblog & Developer Adventures

10-14 September was a week of videos and developer musings.
On video mode, Eva counted 37 days down to the OSMC 2012 with Jeffrey Lensen’s “Case Study – Icinga at”.
Thilo then followed suit with his introduction to Foreman in a nifty video blog post.
In the meantime, Johannes took an adventure in old code that made him appreciate unit tests, documentation and coding guidelines.


Innerhalb der letzten Woche habe ich mich mal wieder etwas intensiver mit einem meiner größeren Software-Projekte befasst, mit welchem ich vor annähernd zwei Jahren begonnen habe. Zwei Jahre sind eine lange Zeit und es kommt immer mal wieder komplett neuer Programm-code hinzu oder kleinere bzw. größere Teile werden überarbeitet. Derart frequentierter Programm-code kann somit völlig unterschiedliche Qualitäten haben und da ich dieses Projekt mit der Absicht die Programmiersprache Python etwas besser kennen zu lernen sowie in die GUI-Programmierung einzusteigen gestartet habe, spiegelt der Programm-code dieses Projekts einen großen Teil meiner Programmier-Fähigkeiten dar die sich über diese Zeit hinweg entwickelt haben.
Die letzte Woche war dementsprechend “abenteuerlich”, besonders wenn man in jene Bereiche vordringt die seit zwei Jahren kein Licht gesehen haben. Da vermisst man schmerzlichst irgendwelche Kommentare ober überhaupt jegliche Art von Dokumentation, denn die ist nicht allzu selten der einzige Hinweis darauf “warum” etwas gemacht wird. Der Programm-code selber sagt einem nur wie und was er macht, aber das alleine reicht nicht wenn zum Beispiel aus anderen Gründen es das einzige “wie” ist das auch funktioniert. Da hilft ein wohl platzierter Kommentar ungemein wenn man im Begriff ist genau das zu verändern und dann aus dem selben Grund wie vor zwei Jahren nach ein und demselben Fehler sucht..
Spätestens wenn Kommentare fehlen und noch dazu der Programm-code an sich sehr wirr gestaltet wurde, möchte man am liebsten alles löschen und neu schreiben, was meist wohl der einzig saubere wenn auch aufwändigste Weg ist. Für solche Fälle gibt es sogenannte “coding guidelines”, an die man sich nicht nur aus Rücksicht auf andere “Leser” sondern auch aus Rücksicht auf sich selbst halten sollte. Die Namensgebung (Variablen, Funktionen, Klassen, etc.), Formatierung (Inline- und Block-Kommentare), Strukturierung (Lokale und Externe API bzw. Module) und unterschiedliche Einrückungsebenen sind nun einmal der direkteste Weg Programm-code verständlich zu gestalten.
Das absolute Nonplusultra allerdings sind immer noch Unit-Tests. Damit erschlägt man sogar gleich mehrere Dinge zugleich: Sie sorgen dafür dass jeder weiß “wie” etwas zu benutzen ist, man kann Ausnahmefälle ganz leicht beschreiben (und spart sich somit die erneute Fehlersuche wenn man zwei Jahre später…) und solange man nichts daran ändert “was” gemacht wird kann man sich gediegen zurücklehnen, falls noch alles funktioniert.
Ich jedenfalls werde versuchen mich weiterhin daran zu halten, besonders wenn ich alles lösche und neu schreibe. 😀

Johannes Meyer
Johannes Meyer

Johannes ist seit 2011 bei uns und hilft bei der Entwicklung zukünftiger Knüller (Icinga2, Icinga Web 2, ...) aus dem Hause NETWAYS.