Documentation — what’s needed & how much is enough?

Hello 👋 technical folks~

Is any (or maybe all) of the scenarios above familiar to you? We’re pretty sure you’ve experienced one of it at least once, especially when the product team doesn’t even have the document drafted. Experiencing these scenarios can be a costly and time-consuming setback, especially if you’re performing a security review for the product.

Documentation — what documents are important to the product team and how much information is enough? Let’s dive right in to today’s article ~

Caveat: This article is written as recommendations based on our experiences; it is not our intention to say that only the mentioned documents are a must-have in your organisation.

Software documentation provides information about the product to software engineers, business analysts (if any), project managers, and business users. There are many types of documentation, and here are some documents we recommend to have within a product team at a minimum:

  • System (design) architecture
  • User-access matrix (UAM)
  • API documentation
  • Test plan
  • List of unresolved security vulnerabilities (aka Vulnerability Risk Register)

And here’s why:

  1. Newly joined team members can get up to speed faster as they can read these documentation on their own, especially when they joined during the project peak period!
  2. These documents ensure that everyone in the team (even those joined recently) will be on the same page; there will be no excuse to say “I don’t know” or “I’m not sure” because “those decisions were made before I joined the team”.
  3. Every member in the team will know what scope(s) will get tested and in which environment, when the testing will happen, and how long it may take.
  4. It provides a way for the team to track all unresolved security vulnerabilities AND to remind the team to fix/update/patch these security vulnerabilities after the release.
  5. External parties (i.e. security reviewers/auditors) will also require some of the mentioned documents as part of their review/audit processes.

So, how detailed should these documents be?

Document shouldn’t be too detailed or too bare; it should contain enough information to let someone (who is new) understand what your system is about. Here are some examples:

  • API documentation
    It should provide an example of every call, every parameter, and responses (including error codes and messages) for each call.
  • Vulnerability risk register
    It should minimally store details like a brief description of the vulnerability information, reported date, probability of its occurrence, impact to the system, interim resolution(s) that is/are currently in place, and the targeted remediation date.

Keeping documents simple and lightweight also makes it easy for everyone in the team to maintain these documents in the future. Besides, no one enjoys reading a very long, detailed, and complicated document, right? 😉

These documents should be revisited and kept up-to-date once every 3 to 4 months, so as to not have any drastic changes to the document(s) or have things slipped off the team’s mind.

We hope that this article has helped change your mind about keeping documentation (if you’re against doing so before this). Documents don’t have to be heavy and complicated; stand from your target audiences’ shoes and think about what they’d need to know to understand or be onboarded!

Documenting down information helps to remind everyone in the team about why certain things are done this manner, especially a few months/years down the road and/or when the initial batch of engineers left/rotated out of the team. Also, remember to update these documents once every few months!

Finally, have everyone in the team contribute to the documents! With that said, all documents should be kept in a place that’s accessible to everyone in the team!

🧙🏼‍♀Team Merlin 💛
Application security is not any individual’s problem but a shared responsibility.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Team Merlin

Team Merlin

Software | Security | Quality enthusiasts doing the right things