WriteTheDocs 2017 – An Alien Looking From the Outside In

Speaker: Meike Chabowski has a Master of Arts in ITE, ended up in IT for 22 years and has started working in documentation at SUSE a year ago.

Observations

Documentation is tedious and takes a lot of work, and not very appreciated. People don't like to admit to needing it, or to reading it.

Software documentation is not just a nice-to-have, but a must-have component of software. Most software products are not usable without documentation. If you work in an IT department, this impacts your work and the success of your business.

Pillars of documentation

Documentation should be provided over a variety of channels, such as whitepapers, blogs, nontraditional channels, classic documentation, and entries/how-tos by external experts, …

Documentation folks can also give trainings, write articles for technical magaizines, and above all support the technical colleagues in communicating tech changes/features etc.

Workflow

Documentarians need super powers since documentation is much more than technical writing (which is a hard skill to learn in itself). When documentation is prepared for release, there is usually not a designated time to write documentation, forcing documentarians to install WIP software which is still heavily bug-ridden to write documentation on the hopefully-to-be finished tool.

The workflow also depends heavily on teamwork. Projects and project states need to be tracked via a variety of tools, such as an issue tracker, a task manager, a source control tool, and tools for writing, editing, and publishing. [I left out many details on workflows and tools here, due to my lack of knowledge hindering my typing speed.]

Considerations

Take constructive negative feedback serious. Stay in communication with them.

Explore other channels and strategies – different things work for different people, so why not try exploring, for example, videos.

Make documentation visible!