Documentation Processes and Types in Software Projects
Documentation is one of the most critical factors in the survival of software, preventing it from becoming “legacy,” and sharing knowledge.
Especially when you have hundreds of developers, thousands of projects, multiple stakeholders, complex processes and a lot of communication processes, you need to keep documenting things.
On the other hand, if you want to become a 10x developer you need to enable/include other developers to the job/project which is a very important skill that you need to have. Documenting your projects is one the most crucial work that will help you to do so.
In a software project without documentation:
❌ The reasons behind decisions are unknown.
❌ Making changes is quite difficult.
❌ Usage, external exposure, and integration are challenging.
❌ What to do in case of errors is unclear.
❌ No company memory
Throughout the project’s lifecycle, various types of documentation should be created. In Trendyol Tech team we are following the below concepts to document our software projects:
✅ At the project’s outset: RFC (Requests for Comments)
✅ During project development: ADR (Architecture Decision Records)
✅ Upon project release: Readme, Release docs, API Docs
✅ In case of errors during the project: Postmortem, Incident State Docs
✅ For recurring (project) operations: Runbook, Playbook
The Productivity Place: Developer Portals
Software documentations typically include comprehensive API references, integration guides, tutorials, and troubleshooting resources, which streamline the onboarding process for new developers and enhance productivity for experienced ones.
Developer portals play a crucial role in documenting software by providing a centralized platform where developers can access, contribute to, and manage those documentations efficiently.
At Trendyol we have tailor made developer portal named Pandora. We are maintaining our software and process documentations on it along with other developer portal features such as service catalog, Q&A platform, productivity metrics, etc.
1- RFC (Requests for Comments) Documentation
When starting a project, RFC documentation is created to make fundamental architectural decisions, gather feedback from different stakeholders about ideas and the project’s progress, reach a consensus, and establish a standard.
RFCs can be considered as a document that you can follow to implement some protocol, an process, a standart etc.
An example of a well-known RFC is the HTTP RFC, which is a protocol used in our daily lives: HTTP RFC.
If you consider to start RFC process in your company you would probably want to create an RFC index to easily search created RFCs in the company.
In Trendyol, we created a standardized RFC creation process and RFC index to keep track all of our published RFCs.
2- ADR (Architecture Decision Records) Documentation
ADR documentation involves keeping a historical record of architectural decisions made throughout the project’s lifecycle, project structure, tools and resources used, and code standards.
In Trendyol, we are creating our ADR documents using a tool called Log4brains. It helps to create/supersede an architectural decision easily via cli commands.
It also has a simple GUI that you can visualize and see your ADR documents historically, here is our Developer Productivity Engineering ADR documentations 👇
Here are more information about ADR process:
3- Readme — API Documentation
A Readme is the first document that you look for a project.
A good Readme should contain information about what the project does, quick start guide, usage examples, performance details, project capabilities, and the individuals responsible for the project. It would be good to have a link to contribution guide too.
In the case of API services, we should also document our “contracts.” This can be accomplished using Swagger/Openapi/Postman collections and contract tests.
4- Postmortem — Incident State Documentation
In the event of errors occurring while the project is live, these records document what was done step by step from the beginning to the end of the process. They detail the origin of the error, the solutions applied, the individuals involved, the actions taken, and the lessons learned.
The Google SRE book has an excellent section on postmortems and incident state documentation, complete with examples.
5- Runbook Documentation
Runbook documentation contains step-by-step instructions for recurring project operations. For instance, it outlines the actions to be taken in case of errors or the steps to follow during updates.
https://atlassian.com/software/confluence/templates/devops-runbook
Thank you for reading so far, I hope it will clear your questions about documenting your projects. May the code with you.
Join Us
We’re building a team of the brightest minds in our industry. Interested in joining us? Visit the pages below to learn more about our open positions.
