Documentation for software developers

Documentation’s lack of popularity among developers, especially on open-source projects, 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.

This training course teaches what to document, what not to, and how to produce documentation without the pain of traditional approaches.

Who should attend

This course is for everyone who works on a software development team, and who wants to be able to produce better software documentation. Especially on teams that don’t have a dedicated specialist technical writer, any team member is in a position to improve the software system documentation, whether or not that you are a programmer.

Attendees must be comfortable writing in English, although excellent written English is not required.

Why attend

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.

After completing this course you will be able to:

• Understand why documentation is a problem
• Understand what documentation is for
• Identify which topics documentation should cover
• Recognise how to improve existing technical writing
• Apply new techniques for writing functional and technical documentation
• Use new tools for producing documentation

Topics covered

This is a one- or two-day course that will cover a selection of these subjects:

• Documentation difficulties
• Documentation requirements
• Content guidelines
• README-Driven Development
• Technical writing basics
• Documenting functionality
• Documenting architecture
• Documenting HTTP APIs
• Documenting product roadmaps
• Other documentation types
• Production pipelines
• Agile software development documentation

These topics mix presentations and guidelines with hands-on exercises that ensure that attendees learn how to apply the techniques they learn about. The exact list of topics is subject to change.

Prerequisites

Attendees will review existing documentation and write their own additions.

Each attendee is expected to bring a laptop with text editor installed that the attendee is comfortable using. Each attendee should also have a GitHub account.