I don't know what's any standardized way out there to write the technical document if any. However, when I write Technical description myself, I follow my custom approach:

Contextualization.

Explain the context, domain, business logic (brief), and the related changesets (with changeset numbers from project management tool ex. Devops, Redmine, etc) that are covered in this technical document. The context will help to link the reader about what has been implemented and what all needs to be taken care of while suggesting an improvement.

Tech stack

If more than one tech stacks are involved, stakeholders and reviewers of related stack can be notified.

Tech Impacts

Mention how new implementation stuff impacted already implemented stuff. Mention descriptively what all is affected and what all is changed. This section is also important during version transitions, migrations and/or upgrades.

Algorithm usage

Instead of bluntly mentioning data and control flow using method/function names, tell the algorithm you have implemented and then refer the respective method/function name if required.
Mention the pros and cons of the algorithm you used with related and supportive diagrams.
Mention performance statistics of your algorithm.

Dependencies

Mention all types of dependency your implementation has. For example, any third party dependency; dependency of another method/function (implemented by someone else); dependency packages/components, etc.
If there are third party dependencies, add their documentation link as a reference for anyone to visit.

References

This section should contain all important reference related to this particular tech doc.
One important reference is the reference to API doc. Add link or path to your API doc.
Other references include the reference to Pull Requests, Code Management tool, Emails, etc.

Tech Research

If you maintain separate research documentation, then link that or directly mention the research points.
The research should be descriptively mentioned so that some other person who bumps into a similar problem can directly go ahead with your work.
Every research and development (small or big) largely contributes to better productivity.

AMD log

A-Added, M-Modified, D-Deleted/Deprecated logs - with names of author, reviewer and iteration number should be mentioned. This is very helpful when to compare the docs of different versions for the same feature. This also helps in tracing out what changes/modifications happened in new versions that weren't there previously.

Note on Sectioning:
I use any of two approaches to section out:

Full-stack - In this you mention all the points (Point 1 to 8) from the client side to server-side and database.
Module wise - In this, you mention all the points (point 1 to 8) for client-side first, then server-side and then database.

I usually prefer writing technical documentation in Microsoft Word for text and Microsoft Visio for drawing diagrams.

Length:
- According to me length does not matter, however parsing of the document should be neat because not everyone will read every part of your document. The respective stakeholder should jump to their part seamlessly. For this, you can provide Table of Contents as well.

If you still feel that document is becoming lengthier and there might be chances of un-readability then divide your document to sub-documents, each document discussing specific internal module. For example, for web service you are attempting to write - jot down modules, you'll cover in individual sub-documents viz. Database Design And Mapping; Impacting Modules and Related Implementation; Client-Side Routing and Rendering; etc.

---

(0)

Login to post a comment!