What’s Up, Docs?

The Importance of Software Documentation

Learning to code using test-driven development (TDD) or README-driven development takes some getting used to. It’s very easy to get wrapped up in writing code that theoretically should work without examining exactly what the code is meant to do given very specific criteria. I had an experience in which I worked a lab, coded everything as I was supposed to, and I was certain that the Ruby methods should work properly only to get test failure after test failure.

Feeling good about your code until you see those red test failures.

Those red lines of text can really get to a person after a while. Hours later and one binding.pry away from smashing my computer to oblivion, I noticed that the spec file had named a variable differently from what I had written in my code. Are you kidding me?!

With that fix, I was seeing green and on my way to a pull request with one very important lesson learned: Software documentation is meant to be read. It tells you what’s up and is there to help you.


What is software documentation?

Software documentation refers to information about a piece of software that explains what it is, how it functions, and/or how others interact with it. There are several different types of documentation, and some may be internal (for programmers) or external (such as instructions for a program end-user).

Software documentation may come in the form of a README, specs (or functional specifications document (FSD)), or even a wiki.

README

Of all the documentation types, the README is considered the most common and most important. The file “contains information about other files in a directory or archive of computer software.” The standard README includes:

  • the project’s name
  • a short, clear description of the project
  • a table of contents
  • system requirements
  • installation instructions
  • information on how to use the program
  • information on how to contribute
  • a list of collaborators and acknowledgements
  • licensing and copyright info

Though there is sometimes more information found in a README, the standard template would include the above items. You can check out some great README examples here.

You may see the README file name written with various casing conventions. It doesn’t really matter much; it makes more sense conventionally when files are listed with uppercase file names preceding those with downcase file names. The README file name in uppercase is to be seen (and, hopefully, read). It’s just like that person who types in all caps or yells all the time — it wants your attention.

Functional Specifications Document (FSD)

How do you know what the program you’re building is meant to do? Functional specifications documents (FSDs) outline how a program should function in a given context. The FSDs can often be mapped using strategies like wireframing. For example, an FSD might have a series of user case statements to explain everything that a user could do and what happens when that event occurs.

“When a user signs up with an email that already exists in the database, they receive an error.”
“When a user clicks the delete button on their blog post, a dialog box opens for user to confirm deletion.”

Not only do these statements help the programmer in building functionality, but it also lets testers know exactly what they should be testing.

Wikis

Though less common, sometimes software documentation comes in the form of wikis, especially if the documentation is more extensive.


The Benefits of Documentation

Documentation provides instruction and expected outcomes. Imagine being hired as a software engineer and having to dive into code with no context of what the software is supposed to do? How do you know what you should be building? The software documentation holds the key to everything that you need to know about the project. If you want to contribute to a project, the instructions on how to do so would be in the documentation.

Documentation helps keep your project focused. How do you go about writing an essay or a blog? You might start by writing an outline of the points you want to cover. You would do the same with a README for your software. When creating a new project, composing a README file first is a great way to clarify the purpose and organize the structure of what you’re trying to create.

Great documentation will make your projects stand out. People are more likely to want to work on a project if it’s clear what it is supposed to do and how others can contribute to it. It can also help you get hired.

During an alumni AMA, a former student of Flatiron School’s online software engineering program recounted how he landed his job as the lead engineer at a company. He was scheduled to have an interview with the prospective employer, but he was contacted prior to the interview happening and told that they had filled the position. The motivated job candidate persisted and created a project to showcase his talents and shared it with the company anyway. In the end, the company ended up offering him the job because they were impressed with the documentation for his projects. If you have two great programmers, the determining factor in who gets hired could come down to who has the best documentation.


Software documentation exists to give instruction and context on how build and use a program effectively. So, when you’re ready to start your next project, create a strong foundation with documentation.


Sources

GitHub Guides — “Documenting your projects on GitHub”
https://guides.github.com/features/wikis/

“Readme Driven Development” by Tom Preston-Werder
http://tom.preston-werner.com/2010/08/23/readme-driven-development.html

“Functional Specification” — Wikipedia
https://en.wikipedia.org/wiki/Functional_specification

“README” — Wikipedia
https://en.wikipedia.org/wiki/README

PurpleBooth/README-Template.md
https://gist.github.com/PurpleBooth/109311bb0361f32d87a2

A curated list of awesome READMEs
https://github.com/matiassingers/awesome-readme

Arch Linux Wiki
https://wiki.archlinux.org/

GIFs from Giphy
https://giphy.com/

Like what you read? Give Winter LaMon a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.