Why Writing Great Documentation Is Essential

Within these castle walls be forged Mavens of Computer Science ...

— Merlin, The Coder

We have all received a product and promptly ignored the thick packet of information that comes with it. This packet usually includes installation instructions, step-by-step assembly instructions, and warnings. Like physical products, software products have lots of documentation too, and, like physical products, it is best practice and in your best interest to write good documentation, and to read it when you can. This way, when you build a software product, the proverbial IKEA couch does not fall apart when you first sit on it. This article goes through the basics of software documentation, types of documentation, how to read it, and how to write it.

Introduction

In brief, software documentation, like any other kind of technical documentation, can refer to a broad range of written work related to the product in question. Documentation in the software world can range from API documentation and "Getting Started" manuals to READMEs, comments, and installation guides. Effectively writing down important features and updates to any computer software or hardware tool is essential for developers and end-users alike. Documentation is a critical part of every stage of the software development life cycle (SDLC). The SDLC commonly refers to six stages of software development:

1. Planning and Requirement Analysis
2. Defining Requirements
3. Designing Architecture
4. Developing Product
5. Product Testing and Integration
6. Deployment and Maintenance of Product

Going Deeper

Read more about the SDLC here:

• "Software Development Life Cycle (SDLC)" (GeeksforGeeks)
• "6 Best SDLC Online Courses to Learn Software Development for Beginners and Experienced in 2021" (Medium)

As you can imagine, each stage of development requires different stakeholders and ways of keeping track of the product, where it is going, and how changes will affect existing and future code. On this large scale, keeping everyone on the same page via proper documentation is critical to minimize confusion and optimize workflow. But, proper documentation practices can and should start with your very first program and GitHub project.

Different Kinds of Documentation

Many different kinds of documentation are written for various audiences and use-cases. This section provides a brief overview of the kinds of documentation you might encounter or hear of in your programming and tech journey. However, it is just an overview. We encourage you to further explore this topic as you need or as you desire based on interest.

Product vs. Process Documentation

On a high-level, software documentation can be divided into product documentation and process documentation. If you are a beginner programmer, you have likely already encountered the former by simply searching up the language you are learning or the platform you are using.

Product documentation describes the product that is being developed and provides instructions on how to perform various tasks with it. In general, product documentation includes requirements, tech specifications, business logic, and manuals.
— Altexsoft, "Technical Documentation in Software Development: Types, Best Practices, and Tools"

Tutorials, how-to guides, source code, FAQs, installation manuals, etc., are all in the product documentation category.

Process documentation represents all documents produced during development and maintenance that describe…well, the process. The common examples of process-related documents are standards and project documentation, such as project plans, test schedules, reports, meeting notes, or even business correspondence.
— Altexsoft, "Technical Documentation in Software Development: Types, Best Practices, and Tools"

For the purposes of this article, we focus more on specific examples of product documentation because they are more beginner-friendly, and any coder can get started with product documentation even in their first program.

Common Examples of Product Documentation

Getting Started

The first document that many users can read about a product is the "Getting Started" documentation. Most programming languages—APIs, operating systems, really anything that requires a process—have a first tutorial. These documents help you get acquainted with the technology in question and provide you with the tools, resources, and confidence to complete more complex tasks with the tools. This kind of doc likely teaches you how to install necessary packages or dependencies and how to write a first program (i.e., Hello World).

Helpful Hint

• Get Started with GitHub Docs
• Getting Started with Swift Docs

Comments

Comments are usually the first documentation that any programmer writes. Comments are written annotations in the source code files and are critical to being able to understand and recall the logic behind the code. Languages use different syntax to indicate comments and style standards. For example, Swift uses a combination of / and * characters. Generally, comments are in the form of block comments that are multiple lines long and inline comments or line comments that span only one line. This article goes in-depth below about how to comment your code effectively.

// This is an inline comment in Swift.
/* This is a block comment in Swift.
   It can go on for a while. */
print("Hello World!")

README

READMEs are a standard text file in any programming project. In fact, on GitHub, when you make a new repository, an option is provided to have GitHub automatically add a README file to the repository. Additionally, GitHub automatically shows the README on the main page of your repository. According to GitHub, a README should include basic information about the project to visitors--what the project does, how users can get started using the project, why the project is useful, etc.

Error Messages

All coders have written code that does not work as expected. It can be stressful or disheartening to see error message after error message. But if you see an error message, it is a golden opportunity to learn and to use a form of documentation. Read the error message! It will help you determine where the problem is, and it will give you a sense of what you can do to fix it.

API Documentation

An API (Application Programming Interface) lets two systems interact. Most of the ways APIs touch our daily lives involve sending and receiving data. For example, when you log into an app, the app makes a call to an API to get your account information and credentials. All kinds of APIs are made and have different purposes. Each API has different calls it makes to get different information in a different format. For example, if you use the IMDb API, you can get different movie and TV show information. Depending on your query, these could range from the cast, to runtime, and reviews. API documentation helps clients actually use an API in their websites, apps, and products.

Using and Reading Documentation

To learn to write documentation, it is critical that you use and read documentation. A common refrain in the tech industry is "Google It." Conveniently, as this article discusses, the tech industry has developed the standard of documenting everything and, in many cases, has made relevant documents available for free to the public. When you Google an issue you are having, you will be inundated with forums, blogs, and official documentation offering solutions to your problem. How to use and read documentation is rarely taught in introduction computer science courses or coding bootcamps. It is a fluid process, much like figuring out how to do research or dig through a library full of resources. When you first see technical documentation, it can be intimidating, so keep in mind the following, which is distilled from a series of articles about reading documentation:

Helpful Hint

Someone has probably gotten stuck where you are before. Someone probably wrote online about how they found a solution.

1. Go find the solution that worked for them. Try it out.
2. If that does not solve your problem, find someone else who asked that question.
3. Repeat until you have figured it out. You probably learned a lot more along the way too!

How to Use and Read Documentation

• Determine your goal.
  • Ask yourself: "What am I looking for?" If you cannot answer this question, you might become overwhelmed with all the information contained in technical documentation.
• Documentation is mostly a reference. Skim until you find what you need, and then read in-depth what is most important to your goal.
  • Documentation can be very dry. It is not meant to be read in one sitting or like a novel.
  • Documentation should be treated like an encyclopedia or a handbook.
• Try different search queries. When you have a problem with your code, try to identify helpful key words to use in your query.
  • Include in your query the specific function or method that you are struggling with
  • Include the name of the platform or language you are using
  • If the above two keywords do not solve your problem, try adding in the version of your language, platform, or operating system
• If you come across a term you do not know, pause, and look it up. This can feel tedious but will teach you a lot, and it will help you be more comfortable with the material you are reading.
  • This will also help you read more documentation more efficiently in the future.

Reminders

• The more you read documentation, the better you get at reading it and writing it.
  • If you are starting as a complete beginner, documentation can be intimidating, and that is okay. Persevere, and you will be a better programmer.
• A human with expertise decided these words were important and would be helpful.
  • This does not mean they will always be useful for your use-case. But official documentation is a good starting place.
  • If the official documentation does not get you to your answer, look for blogs and reputable sources like Stack Overflow, Medium, or Hacker Noon.

Reasons to Write Great Documentation

Help Your Future Self

The first person reading your code again will probably be you. Future-you might have forgotten why past-you made a decision a week ago. Perhaps future-you thinks they have outsmarted past-you and found a cleaner solution or a way to optimize the code. But actually you had already tried that a couple of times a month ago, and forgot to write it down. Documenting your code at every step ensures that you can pause your project and return whenever you want with little hassle.

Best Practice

👍 #Outline Your Code

A great way to "outline" your code is to write inline comments for code sections that serve different functions. This way you can quickly read just the comments and understand what several hundred lines of code does!

Professional Development

As mentioned, companies document everything at every step of the process and about every part of the product. Starting early with commenting and READMEs is a great way to build in best practices at the start of your computer science journey. Writing clear and meaningful comments and READMEs is a great way to showcase your work and your potential as a co-worker. If your public code has uninformative or messy comments (more on this later), other coders or interviewers might have more questions about your quality of work. Also, let's say an interview suddenly comes up, and you have not reviewed a project related to the work you would be doing. Without code documentation, the process of preparing for the interview will be much more time-intensive and laborious than if you had simply put in comments and written a README in the first place.

Community & Etiquette

The last point this article addresses, but not the final reason to document your code, is that you are one coder of millions. By using Swift, Linux, CoderMerlin, Stack Overflow, and other free or open-source technologies, you are greatly benefiting from the public knowledge that others have shared. Commenting your code well, sharing it on GitHub, and sharing what you know via platforms such as Medium is a small way to give back to the community. Get in the practice of helping the next person hoping to learn how to code.

Writing Your First Documentation

Your First Comment

To write your first comment, you need to learn what syntax is used for comments. To find this information, consult the official documentation. For the purposes of this article, we illustrate code documentation using Swift. In the next section, we improve on the documentation.

Helpful Hint

Single-line comments in Swift start with two slashes (//)

// My first comment!
print("Hello World!")

// My first comment! Although this is perhaps expressive of how you feel when writing your first program, it is not that helpful to future coders or others who might read your code. Typically, this line of code would not require a comment because it is self-explanatory—the code prints "Hello World!" But because this is your first program, we can add a redundant comment for practice:

// Prints "Hello World!"
print("Hello World!")

Although redundant, this does provide more information about what the code is doing. If commenting is new to you, err on the side of more comments than less just to get into the habit. As you gain more exposure to other people's code documentation, you will get a better sense of what is and is not helpful.

Your First Function: Toward an API

In this next example, we look at a sample function you might write. This simple function involves variables and a for-loop and conditional statements. It requires some commenting for understanding and adhering to Swift standards. The code is a solution to HackerRank's "Birthday Cake Candles" Problem. The function birthdayCakeCandles() takes in a list of candle heights, and it returns an int of the number of tallest candles (i.e., if the input is [5,3,5,2,1], the function should return 2 because there are 2 candles that are 5 units tall).

func birthdayCakeCandles(candles: [Int]) -> Int {
    var maxHeight = 0
    var numMax = 0
    
    for candle in candles {
        if maxHeight < candle {
            maxHeight = candle
            numMax = 1
        } else if maxHeight == candle {
            numMax += 1
        }
    }

    return numMax
}

The above fundtion has no comments right now. Although the code is only 15 lines long, it would still take someone a few minutes to determine what the function is doing, especially without the problem context. Different kinds of important information can be added to a comment. A best practice you should adopt is to build in information about the following:

1. Who is writing the code?
2. When are they writing this code?
3. Why are they writing this code?
4. How does this code work?

This information helps especially when you are documenting something more complicated, like an API.

If you are submitting code for a class, you can start by adding an informative beginning section at the top of the coding file you submit with your name, date created, and your class section. If submitting in a professional setting, the workplace will likely have its own standards for any comment headers. An example follows:

// Author: Jane Doe
// Date Created: 2021-12-08
// Class Section: Dr. Turing

Then add a section right before the function that includes a concise description, what the function takes in as parameters, and what the function returns. An example is here:

/* Returns number of tallest candles given a list of candle heights.
   Returns: An int of the number of tallest candles
   Parameter candles: An int array of candle heights
*/

func birthdayCakeCandles(candles: [Int]) -> Int {
   ...
}

Last, add in inline comments to describe variables declared and code sections. For example, our solution has a for-loop. This takes up a large section of the code; therefore, it is important to describe concisely the logic of the for-loop:

func birthdayCakeCandles(candles: [Int]) -> Int {
    var maxHeight = 0 // Track tallest candle height
    var numMax = 0    // Count number of tallest candles
    
    // For each candle, check if taller than maxHeight
    // Update maxHeight and numMax accordingly
    for candle in candles {
        if maxHeight < candle {
            maxHeight = candle
            numMax = 1
        } else if maxHeight == candle {
            numMax += 1
        }
    }
    
    // Return number of tallest candles
    return numMax
}

Now, when you put it all together, the file would look something like this:

Helpful Hint

The preamble section at the beginning of the file and before the function are important to keep in mind when you design and document an API.

// Author: Jane Doe
// Date Created: 2021-12-08
// Class Section: Dr. Turing

/* Returns number of tallest candles given a list of candle heights.
   Returns: An int of the number of tallest candles
   Parameter candles: An int array of candle heights
*/

func birthdayCakeCandles(candles: [Int]) -> Int {
    var maxHeight = 0 // Track tallest candle height
    var numMax = 0    // Count number of tallest candles
    
    // For each candle, check if taller than maxHeight
    // Update maxHeight and numMax accordingly
    for candle in candles {
        if maxHeight < candle {
            maxHeight = candle
            numMax = 1
        } else if maxHeight == candle {
            numMax += 1
        }
    }
    
    // Return number of tallest candles
    return numMax
}

That is a huge improvement from the first iteration of the code!

Going Deeper

Apple has its own IDE called XCode, and you can use specific syntax to make your code documentation show up formatted in their Quick Help menu!

• XCode and Swift Markup Essentials (Apple Docs)

A short example of Swift Markup for automated documentation:

/// Calculates a new Point of certain percentage between this point and another                                                                                         
/// - Parameters:                                                                                                                                                       
///   - target: The target point to which to calculate the new Point between                                                                                            
///   - percent: Value between 0 and 1 representing percentage                                                                                                          
/// - Returns: A new point of percent between this point and a target point                                                                                             
public func lerp(to target:Point, percent:Double) -> Point {

In order to generate documentation on the Merlin Server, you may execute (from the root of your project):

make-swift-doc

Your First README in GitHub

When you first start coding, READMEs are one of those ubiquitous but, at times, amorphous files. If you spend any time on GitHub, you will read a lot of READMEs, and they all look a little bit different. Like any other kind of written text file, everyone has their own style, but you should stick with some best practices. As with the other kinds of documentation discussed in this article, always keep in mind:

1. Who is the audience?
2. What is the goal of this documentation? (i.e., What is the purpose of this README?)

Who your intended audience is will determine which concepts you do and do not explain, and how in-depth you go into each section. The goal of the documentation also shapes the content of the README. If you are a beginner coder, it is important to showcase what you have learned, where you learned it, and how you think you could improve a project in the future. The below template is adapted from freeCodeCamp and Request-Response: The Full-Stack Blog.

# Project Title

## Description or Overview

* Describe the problem your program solves or the question your program answers.
* How does your program solve this issue or answer this research question?
* Provide a brief summary or list of the languages (front-end and back-end) and technologies that you used for your project.
* Describe your project deliverables.

## Installation and Requirements

* List or indicate where a user can find all of the requirements necessary to run the code.
* Provide instructions to help the user run your program on their own device.

## Deliverables

* List and describe the outcomes of your project. Did you design an app? A website? A machine learning model?
* Why was this the final deliverable?
* How does the final deliverable work and answer your problem or question posed in the beginning?

## Usage

* How can people use this project in their own work?
* Include screenshots as necessary.

## Future Work

* How can the project be improved upon?
* Are you looking for collaborators?

## Credits

* Did you work with anyone on this project?
* Did you use anyone else's work to debug your code or shape the direction of the project?
* Credit them here!

## Licensing

* Add a license so users know the scope of what they can and cannot do with your code.

Helpful Hint

• Access GitHub's Markdown Style Guide to format your first README. (GitHub's Basic Writing and Formatting Syntax Guide)

Steps to Improve Documentation

Based on the information covered, here are a few tips and reminders when improving documentation:

1. Use the following guiding questions:
   1. Who is the intended audience?
   2. What is my goal for this documentation?
   3. Would I understand this project in a year given how I have documented my work?
2. Read other people's documentation
3. Review old projects AND their documentation
4. Ask friends or colleagues to provide feedback on your projects and documentation

Key Concepts

Key Concepts

• What is documentation?
  • Any written work produced in the Software Development Lifecycle.
  • Product documentation keeps record of how to use the product, what it is, how it works, and how it develops over time. These include READMEs, code comments, API documentation, Getting Started docs, etc.
  • Process documentation keeps record of how the product was made.
• Who writes and reads documentation?
  • Software developers, beginner coders, hiring managers, product managers, and others.
  • In this article, we mainly explore the case of documenting your own code for your future self and future team members.
• How to read documentation
  • Start at the source to the best of your ability.
  • Look up any unknown terms.
  • Look to online forums and communities to answer additional questions.
  • Read error messages!
• How to write documentation
  • Keep in mind your audience and project goals.
  • Err on the side of over-documenting rather than under-documenting.
  • Read other people's documentation to see best practices and think critically about what is and is not working in other documentation examples you see.

References

• https://cds.cern.ch/record/383260/files/p135.pdf
• https://www.sitepoint.com/writing-software-documentation/
• https://medium.com/technical-writing-is-easy/build-great-user-documentation-78f8a1d684e
• https://www.atlassian.com/work-management/documentation/standards