5

Good time of the day, community!

Hope, that my post won't irritate too much, but rather will be helpful for someone in future.

I already made some progress myself (I mean some raw unfinished version of the technical document), and searched across the web - but any extra hints will be welcomed.

Below, I will give a sequential abstract (but precise) description.

What I have:

On my current work I have a web-service. It has:

  1. some user interface

  2. some validation done in fill-in forms within that interface (on frontend level)

  3. list of variants for some of the fields, that are being queried from some internal database using specific sql-conditions

  4. backend logic for processing submitted forms

  5. backend/database logic for storing information from submitted info

  6. some frontend logic for retrieving already submitted info

  7. probably something else technical that I have forgotten to mention

What I need to do:

I need to compose a technical description (with text, tables and probably diagrams) of how the system works (both frontend and backend).

Why do I need it:

We (me, system analyst, and my team of my supervising manager and developers) are going to get this description. Then we are going to look at it, and brainstorm what we can and/or shall change. Then I will make a technical design for things we are going to change/add (if there will be any).

What issues I encountered:

  1. I can't really find any example of (or method for) such document, that would be well-designed and not-so-difficult to understand.
  2. I was looking for some online courses on that, but all of them look very generic.
  3. Both points "1" and "2" above refer to technical description document I need to make now, and technical design document - in future.

Hope for some of your help. And, as I usually say, response is appreciated, ignorance will be understood.

  • 2
    Sounds like a process map to me. It really sounds like you are missing a certain Analyst position in your team and you would greatly benefit from having the correct team members to ensure the work is properly documented. – Shadowzee Aug 19 at 8:06
  • 1
    One starting point is this functional design spec template. – Monica Cellio Aug 19 at 17:24
6

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:

  1. 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.
  2. Tech stack

    • If more than one tech stacks are involved, stakeholders and reviewers of related stack can be notified.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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:

  1. Full-stack - In this you mention all the points (Point 1 to 8) from the client side to server-side and database.
  2. 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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.