Managing documentation on a continuous basis

One of my co-workers asked this week about best practices for documenting applications developed for a client project. As I started compiling guidelines coupled with my experiences, it grew long enough to be its own blog post. So I share it here for everyone to read.

I'm always curious to learn your approaches to documentation and the reasons behind. Let's discuss over e-mail anytime.

An example :

At one of the clients I worked with in Chicago during 2017-2018, I adopted a CHANGELOG coupled with e-mail notifications approach to update stakeholders of the new features added to the project.

At that time, I was working on a Mule app that communicates with 2 database sytems to produce JSONified responses - My primary task was to create RESTful endpoints which would then be used by a front-end developer

Our team was organized such that I work on specific parts of the application code while other engineers take care of pieces that don't overlap with mine.

I prefer a gitflow model of workflow anytime. I maintain branches specific to features and my daily commits into it carry messages specific to the pieces of work done.

  • To learn how I adopt the gitflow discipline to work in a team leveraging centralized version control system, read my series - TFS for Git users

Such an organization of work made it feasible for me to have

  1. A CHANGELOG file similar to NEWS files seen in open source projects from old times.

    Here, I write a single line (and 2 or 3 more lines under it if needed) about the features introduced/bugs fixed.

    This is done at the end of finishing the piece of work and just before merging my feature branch into upstream 'develop' branch.

    The goal is to preserve the decisions made as the app is being developed and the directions the development took as a result.

    If you are breaking a previously set expectation over the interface/usage, this is the place to write human-readable description of it for your UI developers etc.

  2. A README file same as the one you see in well-documented open source projects hosted on Github

    This contains a generic summary of the feature developed.

    Updates to this file are less regular compared to the CHANGELOG file and are typically done only when a feature is considered complete

    The goal is to document how a tester or developer using the feature in their own application might leverage it. Think way far in the future

In addition, I would send an e-mail over the same thread always titled Updates on project XXX noting updated parts of CHANGELOG and links to download any testing collections that may be living outside the source code repository.

The rewriting part is required since not all of the devlopers/managers that receive this email might have access to the source code repository and if you are just attaching links, the e-mail would be worthless to these people.

All these files are supposed to be continually updated as the work progresses.