I used to think documentation was just an optional ''docu-maybe-tion'', but boy was I wrong!😆 It turns out that skipping documentation can really come back to byte you in the code🐍. I learned this the hard way at work, when the previous team left us without a single document, and we had to spend so much time deciphering their code that we could have written a whole new feature in the time it took us!🥲
So, if you want to avoid getting caught in a 'docu-mess', make sure to prioritize documentation in your projects.
What the heck is technical documentation?🤓
Process of creating detailed, accurate, and comprehensive records of a software system's design, functionality, and code. It serves as a valuable reference for developers, stakeholders, and clients, aiding in the development, maintenance, and understanding of the software system.
But seriously why is it required?🧐
Technical documentation is critical in software engineering as it helps developers and other stakeholders understand the system's functionality, design, and code. It acts as a reference for future developers and helps ensure that the knowledge and expertise gained during the development process are not lost. Additionally, documentation can aid in identifying and resolving issues, reducing development time and costs. It also helps maintain consistency in code and design, reducing errors and improving maintainability.
Is there more than 1 type of document?
Requirements documentation: This includes documentation of the requirements for the software system, such as the functional and non-functional requirements.
Design documentation: This includes documentation of the system's architecture, design decisions, and technical specifications.
User documentation: This includes documentation that is intended for end-users, such as user manuals, tutorials, and help documents.
Technical documentation: This includes documentation that is intended for developers, such as code comments, API documentation, and technical specifications.
Test documentation: This includes documentation related to testing, such as test plans, test cases, and test results.
Maintenance documentation: This includes documentation related to maintaining and updating the software system, such as bug reports, change logs, and release notes.
Watch for poor documentation red flags🚩
The documentation is not properly structured or easily accessible to all team members.
There is no established task in the project management system with defined responsibilities and regular deadlines.
Clear standards for documentation, quality assessment, and updates are not in place.
Only a few team members are responsible for maintaining the documentation instead of the entire team.
Without the help of a technical writer, the documentation can be challenging for anyone who needs to access it."
A joint operation🤝
Creating proper documentation is not the responsibility of a single person, but a collective effort of all members involved in the software development process. Documentation is not just limited to developers, but includes the work of different departments, such as designers, analysts, and marketers.
By involving everyone in the documentation process, the resulting documentation will cover all aspects of the software development process and provide complete and accurate information. This collaborative approach also helps to ensure that documentation is not overlooked or neglected in the rush to meet project deadlines. Additionally, having a technical writer with strong technical knowledge and writing skills can help to ensure that the final documentation is not only comprehensive but also easy to understand and use.
Maintaining Up-to-Date Documentation👷♂️
It is crucial to ensure that documentation accurately represents the current state of processes or products.
If neglected, it becomes useless and hinders the development process. To maintain up-to-date documentation, updating should be treated as a parallel task to product development and follow a set schedule.
Employing version control for documentation management can simplify the process and ensure accuracy.
Some of the best tools in market⚙️
Atlassian Confluence: A widely used documentation tool for teams that offers a variety of features such as team collaboration, project management, and content creation.
Git README: A simple and effective tool for creating documentation in code repositories using Markdown syntax.
ReadTheDocs: An open-source platform for creating and hosting documentation, with support for multiple programming languages and integration with version control systems.
Sphinx: A documentation generator tool that supports a wide range of markup languages, including reStructuredText and Markdown.
Doxygen: A tool for generating documentation from source code, with support for multiple programming languages and output formats.
Docusaurus: A Facebook-initiated open-source tool that helps create and publish documentation websites.
These are just a few examples of the many tools available for technical documentation in software development.
Bottom Line🧐
Documentation isn't just for reports, my friend. We document like it's going out of style at every stage of development. It keeps our code clean, our quality high, and our process understandable.
Keep Learning, Keep Growing!🙌🌻
Cheers,
Ujjwal
Connect with me!🤙
Top comments (17)
“ The documentation is not properly structured or easily accessible to all team members.”
I’ve seen so many docs that are either plagued with typos or so much tech jargon that it sounds like Navi(this the language of the blue characters in the movie Avatar). From what I’ve heard from other developers and technical writers, women are often assigned with this task, which is quite strange. Anyway, thanks for writing about this topic. I look forward to seeing more from you! :)
Haha, well said! This cracked me up.
And ughhh... you're absolutely right. It is so wrong to stick this task to women. I think it's really important that folks try to learn to document their own additions to the codebase. Can they have help? Of course, but the builder of the feature is closest to the task and should have a really good understanding of it... putting the work on somebody else just isn't as efficient as getting the person who built the feature to explain it. And hey, it benefits us all to practice our communication and documentation skills!
omg, its so true!
The jargons and the women being assigned to these tasks, you have summed it up quite nicely!
Thanks!
Completely agree. One of the forms of documentation that I usually do before starting new features is planning.
It’s very much like writing unit tests: by writing them, it makes us think in different ways that the system could operate. As a result, we might include additional handling for different use cases that we may not have otherwise thought of. The same is true with a project plan too.
When it comes to system design, I also think it’s helpful to draw up some diagrams. Architectural diagrams help with design and modularisation, and sequence diagrams can show how the systems will communicate with each other.
Once we have those, we have a clear direction and can generally move much faster as a result.
Totally Agree with that Anthony!
What tool/s do you use for system design btw?
To be honest, my initial approach for diagrams is usually quite low tech: pen and paper. I personally find there to be less cognitive overhead by creating diagrams by hand, even if it means I can't move the classes around after drawing them.
If it feels like something that I want to commit to, I'll either just take a photo or try to draw a neater version. Depending on audience, I might try to knock something up in a drawing package. I recently learned of Canva, and it certainly looks like it might make things a lot easier.
Are there any tools that you like to use?
Although I have less than two years of experience in software engineering, I typically use Draw.io to create initial sketches for my projects. However, I also use Camunda Modeler for BPM designs as per the business requirements.
Looks interesting - thanks for bringing those to my attention!
Literally EVERYONE in dev says this. All of the above, we all agree.
And NO ONE does it lol.
Many begin with good intentions and write some great docs...then by six months later the docs are completely irrelevant because no one took the time to keep up with the changes made to the application/site.
This happens to ALL documentation unless it's a very very very static system.
Have you ever used GitBook? I've used it a bit and feel that it's also a pretty good documentation tool. Much less customizable than something you totally selfhost but still pretty nice and you can update via WYSIWYG or raw markdown in GitHub.
great article, but you haven't mentioned the comments/documentation in the code. while not as important for a consumer, vitally important for developers.
If I don't do it, the first who is bitten is probably me coming back in a month or so and wondering what did I do and why...
Thanks for the feedback @webduvet 🙌, totally agree with the idea of adding comments explaining parts of the code, I actually try to practice this in real life, it was so obvious that I forgot to put that in 😅
Counterpoint: If it took you a cycle to get your head around what the code does that probably is a massive time save over devs spending even 5% of each cycle documenting. And it avoids the most common trap of docs - outdated documents that give you a false confidence about what the code does.
Unit tests stay in sync, system tests stay in sync, good variable and method names stay in sync - anything that isn’t executable starts losing relevance and correctness the second you commit it.
It's certainly something to aspire to, but over almost 30 years in the industry (10+ companies from small startup to large corporation) has taught me that it rarely happens... anywhere. What usually happens is that there is a well intentioned effort to document things at the start of a project, but these documents are rarely updated and quickly get out of date to the point where they are all but useless. This then becomes a known fact about the documentation, and they are left to gather dust - usually only ever touched by new hires trying to find their way around an unfamiliar project.
The best way to even come close to solving this is to (largely) let your code be your documentation. You should aim to make it a 'living' document that tells its own story, and enforce a discipline of commenting anything whose purpose/implementation is unclear.
Great point! Rather than relying solely on documentation, using the code as its own documentation can be a smart and effective approach.
While it's important to document requirements and planning during the initial phase for newbies like me to understand the project better😅, adding comments within the code to explain specific features is also crucial.
Thank you, Jon, for sharing your valuable experience and insights!🙌
Its when am getting used to it.
You got it! Thanks for your advises.