Introduction

Overview

Teaching: 5 min
Exercises: 5 min

Questions

• What is software documentation?

• Why do we care about it?

• What are the challenges?

Objectives

• Become familiar with the benefits and challenges of software documentation.

Software Documentation Overview

Software documentation, per Forward, is any artifact made as part of the software development process that is intended to communicate information about the software system about which it was written.

Most people are familiar with this concept and know good documentation when they see it. More difficult, however, is how to write good documentation.

In this lesson, students will learn about the different types of software development and practices and tools to enable better documentation.

The Benefits of Good Documentation

No one would argue that documentation is useful, but here are some of the benefits of good documentation:

• Better Maintainability: Undocumented or incorrectly documented code can do more harm than good. It is difficult to maintain code that does not have sufficient and accurate documentation. Good documentation clarifies what the code is doing in each part and makes it easier to change.
• Improved Team Productivity: Especially for new team members, sufficiently good documentation can help get everyone on the same page and new members up to speed.
• Increased Code Quality: Documenting what you think your code does helps to clear up inconsistencies and can lead developers to refactor something that is needlessly complicated. Overall, documentation has a positive effect on overall quality.

The Challenges to Making Good Documentation

As anyone would tell you, documentation isn’t easy. Some of the challenges involved are:

• Time: Writing good documentation can take time, and especially for projects with unreliable or limited funding, it can become a afterthought. It also introduces potential technical debt if interfaces or functionality change.
• Skill: Writing good documentation is hard. It must be practiced and practiced and practiced. People can become jaded by how much practice it takes to become truly skilled at documenting well.
• Process: Does writing documentation feel unnatural or “clunky” to you? Without proper processes, writing documentation can feel like it’s wasting your precious time.

What do you think of this documentation?

Navigate to https://spack.readthedocs.io/en/latest/ and spend a minute browsing the documentation.

• What makes this good documentation?
• Where is there room for improvement?

Key Points

• Software documentation provides both users and developers information about what a software is supposed to do.

• Software documentation has numerous benefits including improved team productivity, increased code quality, and better maintainability.

• Software documentation can be challenging due to cost and time to maintain.