In this article, I will be sharing how you can create and manage tech documentation more effectively. This will be helpful not only for someone who is starting a new team or a new project but also for a person who is working on an existing product which does not have proper tech/team documentation yet.

Ideally, technical documentation should explain everything about your software product, ranging from internal documentation for the team to external documentation for end-users or other teams. It should contain all the details relating to software products like product designs and requirements, engineering designs, decision records, API contracts, etc.

WHY create and manage tech docs 💡

More effective team collaboration 👏

The team can collaborate better if there is a written note of everything that is currently being worked on. It could even be something that is not yet picked up for work but is finalized for development, like API Contracts, multiple feature tasks, etc. This becomes much more important in a remote job setup.

Improves tech on-call support effectiveness

Tech documentation including the playbooks for commonly faced production issues and support can improve the on-call support effectiveness. This ensures that the team knows and follows the documented SOPs for a certain set of production use cases.

Future references and decision making 👀 🧠

Consider you are working on a service, where you are expected to design and develop the service completely from scratch. There are a lot of important decisions you need to take at this point, like language choice, system architecture, end-to-end user flow, database, cache, messaging queues choices, schema design, etc.

You might have explored a lot of choices before finalizing each of these. It becomes extremely important to document these decision records with all the minute details so that they can be referred to in future if there are similar use cases. This could also be useful for any new joiner who wants to understand the system better and know why we built the system the way we built it.

This also holds true for any modifications in the existing service as well, so that the new devs can understand the trailing changes and the evolution of the service since inception instead of going through the git history, chats and emails.

How to create a tech doc 📑

To start with a team / tech documentation, you can use any preferred choice of documentation platform. I personally like using Confluence docs, but you can choose any other platform as well like git books, or even Google Docs.

You can follow the below template. Note that each point in itself is a separate doc. and the main root doc <Team Name> can have links for each of the child docs

---

<Team Name>

• Members

  This doc should contain information on each team member, like name, email, designation, etc.

• Onboarding Steps

  This doc should highlight all the things that are required for onboarding a new member to the team. This could include listing all the tools, and software needed to set up the codebase locally and also include access-related queries. This doc should also mention in short what the team does and what services (which will be listed below) it handles.

• Product Plans and Logs

  This doc should have links to all the PRDs created and shared by the Product from time to time.

• Service#1: <Service Name>

  • Developer Docs

    • Architecture and components

      This doc should include the HLD(high-level architecture diagrams) of the service and also list all the components used by this service, along with a short explanation, like it's DB, messaging queues, external services, etc.

    • API docs

      This doc should contain the link to Swagger/API documentation created by the developers of this service.

    • Integration

      This doc should mention all the steps that need to be followed to integrate the service into any environment. This could even include steps to request credentials like client-id/secret, etc. to get access to APIs or include additional information on the best practices to follow while integration.

  • Operational Docs

    • Deployment steps and details

      This doc should include detailed steps on how features should be deployed into production and also include pre-deployment(like re-running the previous package build to make sure we have the previous revert version) as well post-deployment steps(like monitoring and revert strategies in case of any incident).

    • Production support playbook

      This doc should mention all the steps and answers to common queries which arise on production support. This could range from customer complaints related to data sync issues or include strategies for resolving system-related issues like the most commonly occurring burst throughput latency spikes, etc.

  • Architecture Decision Records(ADRs)

    This should include links to all the ADRs documented till now. Each file inside this section should be an individual ADR in the below format.

    • ADR0001 - <ADR Title>

    • ADR0002 - <ADR Title>

  • RFCs

    This should include links to all the RFCs documented till now. Each file inside this section should be an individual RFC in the below format.

    • RFC0001 - <RFC Title>

    • RFC0002 - <RFC Title>

(Ideally, each individual ADRs / RFCs should also follow a predefined format which can be decided by your team. The idea behind this is to make the docs informative, crisp, consistent so that it is easier to review and maintain.)

---

Apart from the documents and sections mentioned above, you may add any other section as well based on your use case. For example: if you want to have a log of your previous tasks and the estimations, or even Action items you can add a section like Internal docs within which you can mention the details as per your requirement.

Once you create such tech documentation, it is extremely important to keep it updated as and when any change occur. If not daily, then atleast this should be updated once a week whenever change is required so that the documentation is fresh and always updated.

---

I hope you find this article helpful. If so, please like, comment and share this article 😃.

Let's connect 💫

• Twitter

• LinkedIn

• GitHub

You can also subscribe to my newsletter below to get an email notification on my latest posts. 💻