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 interactive practical workshop 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.
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
This is a two-day course that will cover these subjects:
- Documentation difficulties
- Documentation requirements
- Content guidelines
- README-Driven Development
- Technical writing basics
- Documenting functionality
- Documenting architecture
- 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.
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.