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 dillinger.io.

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 https://docs.nsclient.org.

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

 

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 monitoring-portal.org 🙂

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.

 

Conclusion

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

Autor: Michael Friedrich

Michael ist seit vielen Jahren Icinga Developer 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. Oder schlicht am österreichischen Dialekt der gerne mit Thomas im Büro intensiviert wird ("Jo eh."). Wenn sich Michael mal nicht im Monitoring-Portal helfend meldet, arbeitet er am nächsten LEGO-Projekt oder geniesst das schöne Nürnberg. Oder - at an Icinga Camp near you 😉

Open Source Backup Conference 2017 – Why Backup is so important!

What would you do if your access  of all your electronic data is completely locked?  You’d be a little bit annoyed, it was a trojan who encrypted your files?

Those, who have a backup yet do not have this problem and will smile about it!

BACKUP IS IMPORTANT FOR ALL OF US!
Come and visit the Open Source Backup Conference in Cologne from September 25 to 26.
Two days full of the latest trends and developments regarding Backup strategies with open source software!
Two talks are already confirmed.

  1. Didac Oliveira from Brain Updaters, SLL will visit us in Cologne with his talk on Smart GNU/LINUX Disaster Recovery Management with DRLM&REAR.
  2. Maik Aussendorf from BAREOS will give an insight in the new BAREOS Roadmap 17.2.
    Among others, it includes database backend rewrite, performance enhancements for large installations on database level, NDMP Enhancements, an Amazon S3 Storage Backend and lots of other improvements concerning usability and more languages.

 

More talks will be online soon on www.osbconf.org.

Besides the expert talks, three workshops are also offered on „Puppet“, “Scripting BAREOS“ and „BAREOS Introduction“.

The call for papers is running until June 30! Submit your presentation via the cfp-form on www.osbconf.org. The Early Bird Tickets are also available until the end of June.

Julia Hackbarth

Autor: Julia Hackbarth

Julia ist seit 2015 bei NETWAYS. Sie hat im September ihre Ausbildung zur Kauffrau für Büromanagement gestartet. Etwas zu organisieren macht ihr großen Spaß und sie freut sich auf vielseitige Herausforderungen. In ihrer Freizeit spielt Handball eine große Rolle: Julia steht selbst aktiv auf dem Feld, übernimmt aber auch gerne den Part als Schiedsrichterin.

Monthly Snap May < GitLab CE, Icinga 2, NWS, OSDC, Ubuntu, Graphite, Puppet, SuiteCRM

In May, Achim started with GitLab CE, while Florian presented Vanilla.
Then, Lennart wrote the fifth part of his Icinga Best Practices and Isabel told us about the MultiTech MTD-H5-2.0.
Martin K. continued with external monitoring of websites and services with Icinga 2 while Julia gave a triple hurray to our OSDC-sponsors. Stefan G. gave an insight in his „Mission Loadbalancer Upgrade“ and Blerim tested Ruby applications with RSpec and WebMock.
Lennart published part 3 and 4 of „Icinga 2 – Automated Monitoring with Puppet“, Martin K. showed the benefits of our SuiteCRM Hosting while Marius G. told us the upcoming death of Ubuntu Unity.
May went on with the OSDC in Berlin and the reports from Isabel, Julia, Michi and Dirk.
Then Thomas Widhalm continued with the Carbon Relay for Graphite and Christian wrote about the Icinga 2 Satellite in NWS.
Towards the end of May, Christian announced some new webinars and Gabriel gave an insight in his work at NETWAYS!

Julia Hackbarth

Autor: Julia Hackbarth

Julia ist seit 2015 bei NETWAYS. Sie hat im September ihre Ausbildung zur Kauffrau für Büromanagement gestartet. Etwas zu organisieren macht ihr großen Spaß und sie freut sich auf vielseitige Herausforderungen. In ihrer Freizeit spielt Handball eine große Rolle: Julia steht selbst aktiv auf dem Feld, übernimmt aber auch gerne den Part als Schiedsrichterin.

Incredible Icinga Camp Bangalore

Anfang Mai war es so weit: Für mich ging’s ab nach Indien – genauer gesagt nach Bangalore, das eigentlich seit 2014 Bengaluru heißt und das IT-Zentrum des Landes darstellt. Dort fand im Rahmen der diesjährigen rootconf das erste Icinga Camp überhaupt in Indien statt.

Bereits bei Gesprächen mit Teilnehmern auf der zweitägigen rootconf zeichnete sich reges Interesse an Icinga und natürlich insbesondere Icinga 2 ab. Nicht zuletzt trug auch Bernd mit seinem Vortrag “State of the open source monitoring landscape” im Premiumslot direkt nach der Begrüßung im Hauptsaal der rootconf einen großen Teil dazu bei.

Am 13. Mai, Samstag dem Tag nach der rootconf, war es nun an der Zeit für das zusammen mit HasGeek veranstaltete Icinga Camp in der Thought Factory der Axis Bank. Obowohl (oder vielleicht auch “weil”) der Samstag in Indien eigentlich ein Arbeitstag ist, hatten es viele Interessierte auf das Camp geschafft. Nach Begrüßung und einer kurzen Einführung in den aktuellen Entwicklungsstand von Icinga durch Bernd übernahm Aditya Raj von Snapdeal, einem sehr großen Onlineshopbetreiber in Indien, und gab einen Einblick wie der Einsatz von Icinga 2 dort mittels SaltStack automatisiert wurde.

Nach einer kurzen Kaffepause verdeutlichte Hariram Hari von Fortidm Technologies die Erwartungshaltung aus Großunternehmenssicht an eine Monitoringlösung wie Icinga, bevor dann Toshaan Bharvani von VanTosh detailliert drauf einging wie Icinga 2 mit Ansible provisioniert werden kann. Es folgte zur Stärkung die Mittagspause und dann war auch meine Vortragspremiere gekommen. Mit vielen Slides zeigte ich die vielen Integrations- bzw. Erweiterungsmöglichkeiten von Icinga 2 mit anderen Tools auf.

Roy Peter von Bluejeans Network referierte über die Einsatzmöglichkeiten der Icinga 2 API und zeigte hier insbesondere die automatische Aufnahme neuer AWS Nodes in das Monitoringsystem. Im anschließenden Vortrag ging Bernd noch genauer auf den Director ein, bevor das Camp durch eine offene Runde mit sehr viel Beteiligung einen würdigen Abschluss fand.

Insgesamt bestätigte das Icinga Camp und v.a. die vielen Wortmeldungen nach den Vorträgen (mal wieder) die Verbreitung und das Potenzial von Icinga auch außerhalb der sonst gewohnten Kundschaft von NETWAYS.

Für mich war Bangalore als sog. “Silicon Valley” von Indien eine Chance die ich gerne wahr genommen habe und persönliches Highlight, an das ich mich sicher lange erinnern werde.

PS: Natürlich sind in gewohnter Manier auch wieder Slides und Bilder des Icinga Camps online verfügbar.

Markus Waldmüller

Autor: Markus Waldmüller

Markus war bereits mehrere Jahre als Systemadministrator in Neumarkt i.d.OPf. und Regensburg tätig. Nach Technikerschule und Selbständigkeit ist er nun Anfang 2013 bei NETWAYS als Lead Senior Consultant gelandet. In seiner Freizeit ist der sportbegeisterte Neumarkter mit an Sicherheit grenzender Wahrscheinlichkeit auf dem Mountainbike oder am Baggersee zu finden.

Foreman’s 8th birthday – We will give a party

Foreman Logo

After the success last year we decided to celebrate the 8th Birthday of the Foreman Project again at event room Kesselhaus on July, 27th. As feedback was very good about the provided content we decided to provide the same schedule.

We will start right after lunch at 12:30pm with a hands-on session, so you can do your first steps with Foreman, have a look into latest development or get some inspiration which plugins to add to your environment. There will be some experienced users and developers around to help you, give you some tips for your environment or do some in-person hacking. The demos will showcase several ways of provisioning, configuration management with Puppet and Ansible, orchestration, monitoring integration and other plug-ins.

After a short coffee break we will have 3-5 talks for 30-40 minutes depending on how many speakers I can find. Already confirmed speakers are Ewoud Kohl van Wijngaarden, Michael Moll and Timo Goebel, all being long-term users and contributors to the Foreman Project. I am still looking for someone willing to talk about how he is using Foreman, so if you want to give a case study talk simply drop me a mail.

It would not be a party if we would not have at least some Pizza and Beer afterwards. And the Foreman’s Community guy Greg Sutcliffe already promised some swag to take home with you.

So if you want to join us, please register for free here. This will enable us to order enough food and drinks. We will keep you updated on twitter and on the event page. As a teaser you can watch the recording of me giving a demo at OSDC.

If you can not make it to our event, keep your eyes open for an event near you. For example Julien Pivotto already announced one in Belgium.

Dirk Götz

Autor: Dirk Götz

Dirk ist Red Hat Spezialist und arbeitet bei NETWAYS im Bereich Consulting für Icinga, Nagios, Puppet und andere Systems Management Lösungen. Früher war er bei einem Träger der gesetzlichen Rentenversicherung als Senior Administrator beschäftigt und auch für die Ausbildung der Azubis verantwortlich.

Open Source Backup Conference – Why you should submit a talk!

The call for papers for the Open Source Backup Conference from September 25 to September 26 is still running until June 30.

Interested Speakers are invited to submit their presentation proposals via the call for papers form ob osbconf.org.

What kind of talks are we searching for?
Case Studies, Best Practices, Experience Reports as well as latest developments on open source backup solutions

What affects our decision for a talk?
It should bring a real benefit for the attendees, it should not be a promotion lecture

What awaits you in Cologne?
Two days full of open source backup solutions, meeting the open source community and spreading your know how to the other attendees!

We would be pleased to get your proposals until June 30!

You’d rather join the OSBConf as an attendee? Get your tickets now!

Julia Hackbarth

Autor: Julia Hackbarth

Julia ist seit 2015 bei NETWAYS. Sie hat im September ihre Ausbildung zur Kauffrau für Büromanagement gestartet. Etwas zu organisieren macht ihr großen Spaß und sie freut sich auf vielseitige Herausforderungen. In ihrer Freizeit spielt Handball eine große Rolle: Julia steht selbst aktiv auf dem Feld, übernimmt aber auch gerne den Part als Schiedsrichterin.