Documentation is an under-discussed and under-appreciated side in the process of creating software.
Have you ever stopped to think about the importance of documentation and how it plays a role in your capability to develop software?Â
Think about it, without documentation the job of software engineers becomes immensely more difficult and in some cases, impossible!
Documentation provides software engineers with the knowledge they need to use components required to create software. These documents come in various forms and provide information on the programming languages, utilities, tools and any other components necessary in the development process.
Access to documentation is essential, not only for those working on the software but can also be important for end users. These documents can relate to the technical side of the application, such as API reference manuals or be necessary to understand how to use the application, such as setup and installation guides.
While we can agree that documentation in software development is critical, developers don’t always tend to give it the attention it deserves.
To understand its importance, we’ll cover examples of documentation all developers rely on. We’ll then discuss the role individual developers can take part in to ensure documentation is not overlooked and how documentation keeps the software development world going!
Documentation developers rely on
Programming languages documentation
These are documentation explaining core functionality of the programming language. They exist on websites and can be hosted across multiple sources. These are docs like Python docs, C++ reference, PHP docs, and so on.
Without these documents, essentially software development wouldn’t exist like it does today. Instead, it would be limited only to those who work directly with the programming languages themselves or for those who take the time to understand the technicalities behind a language.
The existence of documentation essentially reduces the barrier of entry to work with programming languages and their related utilities.
A huge part of ranking programming languages today also boils down to the quality of the documentation. For example, Python is known for its comprehensible documentation which has likely contributed to its rapid rise in popularity.
For programming languages, documentation is an absolute requirement to communicate the existence of a language. There are probably many programming languages that existed but no one ever heard about or bothered to use them because of non-existent documentation!
So take a moment to appreciate all the people who went through the process of writing these documents.Â
You think writing an instruction manual for your application isn’t fun? Try writing the documentation for an entire programming language!
API reference manuals
These are documents explaining exactly how to use an API to allow interaction with a program. This is another form of documentation sharing information from developer to developer.
For closed source programs, API reference manuals is essentially all you have to allow interaction with such programs. In this case, the documentation is arguably more important than the existence of the program itself. Without documents to provide information on them, no one can make use of the programs functionality.
If you work on creating APIs, documentation should receive the same level of attention as the development of the program itself. Whether or not you follow best practices and place effort to ensure your documentation is clear and comprehensible will be reflected in how well your API is noticed and adopted.
Source code repository documents
These are the documents placed in the repository of a source project to provide any necessary details about its contents.Â
Typical documents in a repository include the Readme file for an overview of the repo, Contributions file for how to make your contributions, License descriptions, Code of Conduct and so on.
Related: The essential checklist for every open source repository maintainer
If you come across an open source repo with completely non-existent documentation or information you’re unlikely to stay for very long. The fact is, no one wants to have just source code to work with.
So if you want others to use and get involved with your projects you’ll need to take the time to have some form of documentation in place.
Requirements
This describes documents that capture any business, customer or use cases about the requirements of a software product or service.
Understanding the purpose of a product plays a role in its implementation which is why creation of such documents is an essential step in the software development process.
Organisations creating a product for a particular market will especially pay attention to such documents. Having requirements documents in place ensures the needs of a market are captured from an early stage and can be used to check the resulting product is compliant with these needs.
Capturing requirements can also form part of defining a Minimum Viable Product (MVP) which describes the minimum features a product needs to meet its main purpose.
Without an MVP, you and your team may find yourself endlessly working on projects with no end goal in sight. Requirements should be as clear and concise as possible and aim to establish the Definition of Done.
Related: 5 Reasons why developers fail to complete side projects
However, don’t think this side of documentation is something you should ignore if you’re not directly involved in a customer facing role.
All software products are written for a purpose, and whether for yourself or for others, having something to describe what the end goal is will be valuable in driving the development to ensure a successful product.
Your role in the future of software documentation
Do you care enough about documentation?
Developers tend to see documentation as a formality and not an essential.Â
But isn’t that interesting considering every developer themselves relies on the documentation of others to carry out their work?
Remember those people who write docs for programming languages? And the reference manuals for APIs you use?Â
We rely on someone else above the chain to make our work easier or even possible at all.
Documents written by those involved with programming languages were necessary for another set of people to write libraries and frameworks based on that programming language which was in turn necessary for you to work with those libraries and frameworks.Â
There are also many more parts to the chain, with documentation for your compilers, interpreters, IDEs, source code management system and much more all being necessary in the process of creating software programs.
Fundamentally, it requires the effort of the developer that understands core functionality of these technologies and tools to properly document and share knowledge with others.Â
If you work with software, you also have a part to play in documenting your work so it can be used by others. See it as your responsibility to properly document any projects you have a key involvement in to ensure knowledge can be passed on and this chain doesn’t break.
Help your future self
Apart from passing on knowledge, documentation also acts as a method of recording any important details and thought-processes so you don’t forget about them.Â
Don’t make the mistake of thinking just because you were highly involved in creating something that you’ll always remember everything about it! Â
 “The horror of that moment,” the King went on, “I shall never forget!”. “You will, though,” the Queen said, “if you don’t make a memorandum of it.” – Lewis Carroll (Through the looking glass)
Of course, documentation here is the solution to ensure as much as information can be captured and help whoever needs it now or in the future, including your future self. Â
If you lead a team, make documentation part of the deliverables for every project so knowledge is not dependent on individuals.
Anything not obvious should ideally be written down but there’s also a limit in how much time will be spent capturing every minute detail of a project. The key is finding a balance and allocating the appropriate amount of time to capture important information about a project.
Also consider having a cloud based method of recording your information. For example, Trello, which is an online task management platform can be used to easily keep track of anything relating to your project and provides collaboration facilities for software teams.
Related: Using Trello to organise your dev projects
Video documenting can also be an option if that’s your preference, just make sure important information is recorded… somehow or anyhow!
The bare minimum...
If by now you’re not convinced you should take documentation seriously, I urge you to consider committing to at least one form of documentation for every project you work on.
If it doesn’t sound appealing to you to have multiple documents capturing different aspects of your project, consider a single document to list the bare minimum needed for someone to use the resulting product or application.
As a bare minimum, I suggest simply creating a Readme file in the repository for all your software projects. Readme files have become an unofficial standard in software development and anyone visiting a repository these days will expect to be greeted by one.
If you use GitHub to host your repositories there is even an option to initialise a Readme file when creating the repo.
For good practice, ensure the Readme at a minimum captures an overview of the project, any technologies used in its creation and how to install and use the contents of the repo.
It can seem cumbersome to have to pause in the middle of a development task to write things down. You can handle this by writing bullet point notes while in the middle of development then going back later on to add more detail to these points.Â
As programmers, we take time and effort to create programs that will be of use to others. Without some form of documentation, it will be difficult for others to adapt our work and the lack of information can render it unusable.
So why wouldn’t you put in extra effort to document and ensure your work has paid off?Â
Conclusion
Documentation provides a means to easily share knowledge and will make things easier for you and others when working with software.Â
Software engineers need to work on being more intentional at documenting and to see it as a significant part in the process of developing software. We all have a role to play when it comes to ensuring our work is documented and can be easily distributed and used by end users or other developers.
So why should you be obsessed with documentation as a developer? Because it’s necessary for the world of software development to go round, literally!
Do you have any thoughts about the importance of documentation in software development? Leave a comment below.
See other articles you may be interested in below: