Why Writing Great Documentation Is Essential

From Coder Merlin
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[edit]

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.[1] 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).[2][3] 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 DeeperGoingDeeperIcon.png
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.[3] But, proper documentation practices can and should start with your very first program and GitHub project.

Different Kinds of Documentation[edit]

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[edit]

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"[3]

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"[3]

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[edit]

Getting Started[edit]

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).[4]

Comments[edit]

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.[5] 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[edit]

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.[6]

Error Messages[edit]

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[edit]

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.[7] 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.[8] API documentation helps clients actually use an API in their websites, apps, and products.[9]

Using and Reading Documentation[edit]

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:

Hint.pngHelpful 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[edit]

  • 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.[10]
    • This will also help you read more documentation more efficiently in the future.

Reminders[edit]

  • 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.[11][10]
  • A human with expertise decided these words were important and would be helpful.[11]
    • 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.[11]

Reasons to Write Great Documentation[edit]

Help Your Future Self[edit]

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.[12][13]

Best PracticeHintIcon.png
👍 #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[edit]

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.[13] 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[edit]

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[edit]

Your First Comment[edit]

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.

Hint.pngHelpful 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!"[13] 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[edit]

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).[14]

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:

Hint.pngHelpful 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 DeeperGoingDeeperIcon.png
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!

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[edit]

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.[15][16]

# 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.
Hint.pngHelpful Hint

Steps to Improve Documentation[edit]

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[edit]

Key ConceptsKeyConceptsIcon.png
  • 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[edit]

  1. "Overview Software Documentation." (GeeksforGeeks 2021) Accessed December 6, 2021.
  2. "Software Development Life Cycle (SDLC)." (GeeksforGeeks 2021) Accessed December 4, 2021
  3. 3.0 3.1 3.2 3.3 "Technical Documentation in Software Development: Types, Best Practices, and Tools." (Altexsoft 2020) Accessed December 4, 2021.
  4. "API Getting Started Tutorials." (I'd Rather Be Writing 2021) Accessed December 8, 2021.
  5. "Comment (Computer Programming)." (Wikipedia) Accessed December 8, 2021.
  6. "About READMEs." (GitHub Docs 2021) Accessed December 8, 2021.
  7. "What is an API and How Does it Work?" (Towards Data Science 2019) Accessed December 8, 2021.
  8. "IMDb API." Accessed December 8, 2021.
  9. "What is API Documentation." (Technical Writing is Easy 2019) Accessed December 8, 2021.
  10. 10.0 10.1 "8 Tips to Reading Documentation: A Newbie’s Guide in 2021." (Tech Talent South 2020) Accessed December 8, 2021.
  11. 11.0 11.1 11.2 "How to Read Your Way to Becoming a Better Developer." (freeCodeCamp 2018) Accessed December 8, 2021.
  12. "Why documentation matters, and why you should include it in your code." (freeCodeCamp 2018) Accessed December 8, 2021
  13. 13.0 13.1 13.2 "Putting comments in code: the good, the bad, and the ugly." (freeCodeCamp 2017) Accessed December 8, 2021.
  14. "Birthday Cake Candles" Problem. (HackerRank) Accessed December 9, 2021
  15. "How to Write a Good README File for Your GitHub Project." (freeCodeCamp 2018) Accessed December 14, 2021.
  16. "Professional README Guide." (Request-Response: The Full-Stack Blog 2021) Accessed December 14, 2021.