Peter Hilton - Speaking & training

Documentation for software developers

A workshop on better ways to document software

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:

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.


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:


Share on TwitterShare on LinkedIn