Skip to main content

Section 6.1 Documentation Matters!

Quality documentation is essential to open source communities because decisions and processes need to be communicated to a distributed team of developers as well as to future developers. In addition, even seasoned developers might write some complicated code, and if they come back to it six months later, even they might not easily remember why a particular change was made or understand precisely how it works without good documentation. But, these are just two of the many reasons documentation matters in open source.
Any time you want to understand why a page in Wikipedia is edited a certain way, the history and discussion buttons reveal a rich level of information and interaction that are the backbone of what makes it a useful and reliable source. Look at each of the following links that serve to document changes to the Wikipedia page on software documentation:
In open source projects, documentation is much more than developer documentation in code and README files.
Every technical effort has requirements for different types of documentation. The project’s ability to make writing, editing, and publishing as easy as possible is the main key to attracting and retaining contributors.
Correcting documentation is often one of the first contributions that new contributors make to a project. This is because it is often the easiest way to get started. According to Mozilla, potential contributors prefer preferred simpler tasks to more challenging tasks, and shorter tasks to long tasks. They found when given simpler choices, the percentage of people who engaged with the Mozilla contribution page by either choosing a contribution task or selecting not-ready was 60%, much higher than the 15% engagement rate the page had seen before they began looking into potential contributor preferences. See Participation Lab Notes: Short Simple Tasks Increase Engagement
for more information.
In open source communities documentation is a key tool. Documentation needs to exist to explain why decisions were made, how to get things running, how the code is organized and works, and what steps must be taken to contribute. You have to document everything that you do in a open source project, and this is not just with the code. Next year when you need to remember why a technical decision was made, the answer should be readily available in the documentation.

Subsection 6.1.1 The Purpose of Documentation

What do you think of when you think of documentation in OSS? Do you think of the README or LICENSE or CODE_OF_CONDUCT or other files often found in the root of the main code repository? Do you think of source code documentation? Do you think of documentation made by documentation generators such as Doxygen, Javadoc, NDoc, or others? Do you think of tutorials or user manuals? Do you think of the list of open merge requests and related discussions for a project? Do you think of release notes or other documentation accompanying specific versions of the software? If you think of these, then you are on the right track, but documentation in a typical OSS project often includes even more.
Because many projects have widely distributed, volunteer developers and other contributors, documentation is key to keeping the project on course. Note that the specific documentation included in a project repository can vary widely depending on the project and its goals.
In addition to source code, each OSS project typically contains a set of specifically named documentation files. The following are often included:
    Arguably the most important file in any open source project, the README file typically contains an overview of the project, and what problem it solves, as well as instructions on how to get started, information on how to contribute, and many other pieces of information that are important to that particular OSS project.
    Documenting changes to the project over time, the CHANGELOG usually includes a list of all releases and a summary of the changes that were made in each one.
    Outlining the behavior expected of all contributors and users of the project, the CODE_OF_CONDUCT is intended to ensure that the project is welcoming and respectful to all. If you are interested in getting involved in an OSS project, be sure to read this file not only so you know how you should behave, but also so you know how you can expect to be treated.
    If you are at all interested in getting involved in a new OSS project, the CONTRIBUTING file is key because it provides guidelines for contributors, including how to report bugs, how to submit proposed code changes, and how to get help.
  • FAQ.
    As is typical outside of OSS, FAQ provides answers to frequently asked questions about the project.
    Containing instructions on how to install and set up the project. Note that the INSTALL file is typically not the same as how to set up the development environment to contribute to the project.
    As explained in Chapter 5, the LICENSE file specifies the terms under which the project is licensed. It outlines what one is and is not allowed to do with the code.
    The TUTORIALS file contains or links to tutorials or guides that help users understand how to use the project.
    Outlining the project’s plans for future releases, the ROADMAP is useful to new contributors to understand the direction of the project.
Some types of documentation utilize a particular structure often provided by the repository platform. We have discussed some of these earlier. Some very common kinds of documentation of this type are:
  • Bug and/or Issue Tracking.
    Bug and/or issue trackers provide tracking information for bugs, feature requests, or general issues that have been identified in the project. They typically include related reports with steps to reproduce the issue or bug, the expected behavior, and the actual behavior. More about bug and issue trackers is covered in Section 6.4.
  • Continuous Integration and Continuous Delivery (CI/CD).
    While not used in all projects, larger OSS projects typically use CI/CD (continuous integration, delivery, and deployment) tools and processes in order to provide ongoing automation and continuous monitoring throughout the software lifecycle.
  • Editing and Review.
    As we learned in Section 4.6, Software Engineering Collaboration Platforms like GitHub provide a forum for code reviews, proposed edits, proposed updates, and discussions of these via merge or pull requests. These are also a dedicated forum for discussing a proposed feature or bug fix.
  • Project Management.
    Certain project management tools, such as Kanban boards, GitHub Projects, Trello Boards, etc. are often be used to organize and track the progress of documentation-related tasks and issues. These tools typically provide a visual and flexible way to manage the workflow of creating, updating, and maintaining documentation within a OSS repository.
  • Version control.
    Version control is documented through git or another VCS. See Chapter 4 for more detail.
Depending on the project, many other types of documentation might be found in the project repository including documentation that is not easily contained in a single file or a single tool. This type of documentation includes:
  • Design documents.
    Design documents provide detailed information on the design and architecture of the project. They often include diagrams, flowcharts, and other visual aids to help developers understand the project’s structure.
  • Developer documentation.
    Developer documentation provides information that is useful to developers working on the project. They often include coding conventions, APIs, and other technical information.
  • Feature specifications.
    Similar in purpose to a ROADMAP file, feature specification documents provide detailed descriptions of the features that the project is expecting to implement. They often include use cases, functional requirements, and technical specifications.
  • Help documents.
    Help documents provide information on how to get help if you are having problems with the project. They often include contact information for the project’s support team, as well as troubleshooting tips and frequently asked questions.
  • Release notes.
    Release notes provide information on the changes made in a particular release of the project. They often include a list of bug fixes, new features, and other changes.
  • Test plans.
    Describing the test cases that are used to test the project’s functionality, test plans often include test scenarios, expected results, and test data.
  • User manuals.
    Providing instructions on how to use the project, user manuals often include step-by-step instructions, screenshots, and troubleshooting tips.

Subsection 6.1.2 Effective Documentation

Part of your journey is learning how to navigate the project’s documentation to understand such things as how to get your development environment set-up, how to conduct yourself, as well as how you to contribute if you are so inclined. If you do want to contribute, you will be contributing not only to code, but to the historical documentation of that code.
Documentation is a sanity-preserving tool for users of and potential contributors to your project, including your future self and perhaps your future boss or coworker.
If you needed to find out who had made a particular commit to the code in version control and why they did it, you would want the project to use tools and processes with effective documentation.

Checkpoint 6.1.1. Exercise: Navigating poorly documented code.

Consider the following function for two minutes to see how far you can get just by looking at the code snippet alone.
def findAllPrevious(self, name=None, attrs={}, text=None, limit=None, 
    return self._findAll(name, attrs, text, limit, self.previousGenerator, 
Was two minutes sufficient to understand it? Even if you had written this code yourself six months ago, how likely would you be to remember what it does now? Briefly explain.
Now consider the prototype with a docstring.
def findAllPrevious(self, name=None, attrs={}, text=None, limit=None, 
"""Returns all items that match the given criteria and appear 
before this Tag in the document.""" 
    return self._findAll(name, attrs, text, limit, self.previousGenerator, 
Now go to the following link: Documentation Example
and consider it.
Which of the above methods gives you the quickest idea of how to use this particular function? If you had to figure out how to use this function from an XML parsing library, which level of documentation do you hope the code would have? Explain.

Checkpoint 6.1.2. Exercise: Practice good code commenting.

Throughout all the exercises in this book practice writing good commit messages as well as effective commenting and documentation for your coding efforts.
  1. Write thorough comments in all your source code.
  2. Trade sources with another student and attempt to make sense of the source from the documentation alone.

Checkpoint 6.1.3.

    Which of the following statements best captures the role and significance of documentation in open source projects?
  • Documentation is primarily used to outline the project’s future plans and visions.
  • While the ROADMAP can provide insights into a project’s future plans, the primary role of documentation spans far beyond just outlining future visions. Documentation serves to communicate a wide range of information, from code functionality to contributor guidelines.
  • The LICENSE file is crucial because it contains step-by-step instructions on how to use the software.
  • The LICENSE file primarily outlines the terms under which the project is licensed, specifying what one is and is not allowed to do with the code. It doesn’t provide step-by-step instructions on using the software.
  • One primary purpose of documentation in open source is to explain why decisions were made, helping future reference.
  • Correct! Documentation in open source projects serves a critical purpose in explaining the reasoning behind decisions, aiding in both current understanding and future reference.
  • Documentation is mainly for external users and not for the development team.
  • Remember, documentation is not just for external users. Even seasoned developers benefit from well-documented code, especially when revisiting complex code segments after a significant duration.
  • Documentation in open source projects is usually limited to the README and LICENSE files.
  • Documentation in open source projects is comprehensive, encompassing a range of files such as README, CHANGELOG, CODE_OF_CONDUCT, and more. It’s not limited to just README and LICENSE files.
You have attempted of activities on this page.