Documentation for software developers

Documentation’s lack of popularity among programmers is at least partly due to time wasted on too much documentation, and producing docs the hard way. However, neglecting software documentation and technical writing skills holds us and our projects back. The solution is to improve basic skills, integrate documentation with modern software development methods, and learn about modern tools. Topics include:

• Documentation requirements - understanding why we need system documentation
• Content guidelines - deciding what to document
• Technical writing - learning techniques for effective writing
• Documentation types - comparing essential documentation with special-purpose docs
• Production pipelines - using tools to produce software documentation
• Architecture and code improvements - reducing the need for documentation
• Project management - agile documentation planning and project risk reduction

This workshop teaches what to document, what not to, and how to produce documentation without the pain of traditional approaches. Attendees will learn to write and publish effective documentation with less effort, and develop a long-term skill. This benefits all software development teams, because good system documentation is a universal software requirement.

Video

Equipment & organisation

The workshop includes group discussion and exercises that attendees can work on individually or, ideally, in groups of 2-4 people. The exercises use paper handouts, pens and sticky notes. Attendees do not require a computer, to avoid technology distractions, but can download the handouts if they prefer not to work on paper.

Schedule & session outline

The workshop is based on 20-minute sessions, each with a group discussion or exercise, and ends with a wrap-up. The following list of sessions forms a basis for a schedule, which retains flexibility to adapt to group size, progress and interests.

1. What’s wrong with current documentation? Group discussion: current problems with docs, followed by documentation goals and how to do it better, then documentation requirements and deciding what to document.
2. README Driven Development - a technique for Minimum Viable Documentation. Exercise: develop an outline for the ideal project README with sticky notes.
3. Technical writing techniques - learn the basics for better documentation. Exercise: Critique and review a documentation sample, and apply the presented techniques.
4. Documentation process. Exercise: map out your own ideal documentation process with stickies, to identify documentation tasks, roles and key events.
5. Documentation-avoidance. Exercise: group quiz with examples of architecture and code that can improved to make its documentation unnecessary.
6. Wrap-up.

Depending on the length of the workshop, more or fewer 20-minute sessions can be accommodated but experience shows that having this format works well. A longer workshop would extend sessions to 30 or 40 minutes or include additional sessions such as:

• Integrating documentation with agile software development methods
• Documentation for open-source software projects
• Manpage Challenge: write a single page of documentation (or README) for your open source project.
• Getting started with a documentation publishing toolchain (readthedocs.org or GitHub Pages).

Conferences

• ACCU 2017 - 27 April 2017 (rated 83% green, 17% yellow, 0 red; 24 votes)
• I T.A.K.E. (Un) conference 2017 - 12 May 2017
• Agile Cambridge 2017 - 28 September 2017