Writing Better Documentation for Software Engineers

Published in

The Startup

5 min readSep 28, 2020

I believe that most software engineers will agree with me that documentation is a good thing, however, it is quite lacking in the real world IMO due to various reasons such as

Legacy systems that don’t have good documentation because such a practice of writing documentation wasn’t promoted back in the day
Lacking standard across the organization/team for writing new documentation or updating existing one when the corresponding code is modified
Too many things on the plate of an engineer. Oh man, now we have to focus on writing documentation as well, sigh.

Traits of a Good Documentation

Self explanatory

Often times, I read documentation/code comments where I am still left wondering as to what is going on?! Lack of context with the use of words adapting special meaning from the time when the code was written impedes understanding. Always assume that the context is lacking and the goal is to develop the context rather than writing documentation relying on the understanding of the given context

Readability

Focus on easy writing that can be understood by the masses. Usage of complex English constructs will just hinder assimilation of the concept delineated in the document. In easy words, focus on content rather than complex English ;)

External Links

If the document relies on third party resources, then leave a link(s) to the resources. For example, if a technical paper or a video was used in the development of the source code then leave a link. Doing so, will allow others to better understand the logic by referencing the same materials

Evolving

Documentation is always changing and as such effort needs to be made to alter it as necessary. What sucks more than no documentation is stale documentation that hasn’t been updated in years and leaves the reader with incorrect knowledge of the underlying system

Validated

A good document will have been validated by at least another person on the team or the organization, preferably more. The writer shouldn’t claim the document to be good after writing it unless validated.

When to document

Note: Python isn’t my first language so please let me know if you spot any errors

Function Signature

Type agnostic languages can be a huge pain point in the long run where the incoming function parameter’s type and structure is unknown. Time and time again, I’ve had to track the call hierarchy to understand the function parameter’s structure. Leave a comment with a sample input to the function so that readability increases multi-fold.

Note: Running a python program isn’t always straightforward when it takes in a plethora of arguments and each argument is a path to various artifacts in the file system. It can get quite cumbersome to understand since some of the input to the program could be an output of another team so it already represents a layer of opaqueness.

def process_input(input):
    '''
    @param input: { key: “Hello”, value: Foo } # Makes it clear that `key` is a string and `value` is an instance of `Foo` and `input` is a dictionary    @return None
    '''    abc = input.get(‘key’, None) # We know now that `abc` is a string without running the program

Special Hacks

Write comments about special quirks (“hacks”) put in place so that it easier to reference long term as well as for a new incoming member

def process_input(input):
    '''
        ...
    '''    # Based on the input argument ‘use_special_logic’ to the script, use the special logic put in place to fix bug://12345678 (ticket #)
    # TODO: Replace handling of this special logic bug://12345679
    if input.get(‘use_special_logic’, false):
        special_logic()

Business Logic

Tech is being adapted rapidly in various industries so coming into an industry-specific software company, it is quite plausible that an engineer isn’t aware of why a certain logic was put in place

def buy_call_options_contract(premium_on_one_share, number_of_contracts):
    '''
       Holder of a call option contract has the right but not the obligation to exercise the contract. By exercising one call option contract, the holder is purchasing 100 shares at the price listed in the call option contract. For more information on call options, please refer to the document titled: 'Call Options' in the shared team folder at link
      
       @param premium_on_one_share: float The price of one stock. For example: $4.47        @param number_of_contracts: int Number of contract        @return True if successfully bought the call options otherwise False        @note It is upto the caller of the function to validate input types and values
   '''    # One option contract is a holder of 100 shares
    contract_price = premium_on_one_share * 100
    total_price = number_of_contracts * contract_price
    ...

Script Usage

Maintain a comments section above each script explaining usage and different ways to run the script as well as the various outputs. Also, maintain a usage() function and print all the parameters upon incorrect invocation of the script

'''   Sample Usage:   python render_tiles.py -u 4 -t hello -cd   // Corresponding output/impact   python render_tiles.py -zf -u 5   // Corresponding output/impact'''

Concept Documentation

Sometimes a concept/feature spans multiple code files/functions so it is hard to document it in the code. For this, I prefer explaining this concept in the file on the team’s shared folder. For example, one can place the service behavior in this document, different types of requests/responses or other big concepts.

# Written in Markdown# Options System## What are options?
...## Technical Stack
...## Architecture Diagram
...## Testing
...## Internal/External Clients
...## Rollout
...## CI/CD Links
...## Links
...## Special business logic
...

Research Documentation

Please maintain proper documentation similar to ‘Concept Documentation’ (above) for the research you’ve conducted for a new feature request or a tricky bug fix such as a race condition. In fact, I looked into an issue of intermittent test failure and it was quite tricky to solve and led me to use a wide variety of tooling before I was able to understand it. I wrote all of my research in a document and now it can be referenced later.

# Feature: Provide a Python library around lib.so## Research### Cython
...### Swig
...## Architecture Diagram
...## Team Feedback
...## Others
...