It Can Be Love: Developers and Documentation!

After working 22+ years in the IT industry, and more than 16 years at SUSE, it’s amazing to see that – still – you live and learn.

In spring, when I was just fresh and new in the documentation team, I wrote a blog about my first weeks in engineering. One comment I made was „Developers normally love to write code, but not necessarily text. Most developers are geniuses in writing their code, but not necessarily in explaining it.”  That was what I had heard and seen so far …

Roughly six months later, I have to partially revise my words. Indeed, I found developers who like doing documentation work.

At the Write The Docs conference (see Janina’s blog) we had the pleasure to meet Dr. Jan Christian Krause from Hamburg/Germany, who is working as programming software architect at iteratec in Hamburg. He delivered a very good speech about API documentation – and he happily confirmed that he really loves to write documentation.

And just yesterday, while doing some research for a project, I came across a recent article about the latest YaST Sprint, published by my colleague Ancor González Sosa. One chapter is all about the cooperation of the YaST team with the documentation team – here is what Ancor wrote:

“Usually developers love to create programs loaded with cool features but hate to write documentation. Fortunately there are people out there who enjoy writing documentation and bringing all those features to light.

We have already mentioned in previous reports how grateful we are for having the SUSE documentation team polishing and publishing our documentation drafts and how open and straightforward the process is.

We updated the YaST documentation to include information about the installer self-update feature, which will debut in SUSE Linux Enterprise 12 SP2 and openSUSE Leap 42.2. As part of the same pull request and in the AutoYaST side, some additional improvements were made, including cleaning-up some duplicated information about SUSE registration.

On the other hand and as a consequence of the above mentioned new feature, the AutoYaST documentation regarding user’s management has been rewritten, adding missing information like groups, user defaults and login settings.

All our pull requests are already merged in the doc-sle repository. At a later point in time, the SUSE documentation team will review and polish all the new content (including ours) and will publish an up-to-date version of the online documentation. If you don’t want to wait, you can easily generate an HTML or PDF version of the documentation including all the non-reviewed contributions just following the very simple instructions in the README file of the doc-sle repository [on GitHub].

Did we already mention we love the open source, programmer-friendly processes of the documentation team? 😉”

Dear YaST team, thank you very much for your continuous support, your contributions to the SUSE documentation, and your encouraging words! We deeply enjoy working with you and the many many other talented and ingenious developers at SUSE! We love to hear that you love working on documentation!  And we are sure that you are not alone .

Disclaimer: The text at hand has not been reviewed by a native speaker. If you find typos, please send them to me (meike.chabowski@suse.com) – or if you like them, just keep them :-).