There are two forms of documentation that I really value and will gladly devote my time to maintaining, READMEs and Architectural Decision Records (ADR).
Having taken responsibility for many existing projects at various stages of development, I have felt the pain of trying to figure out the why, where and how of an application.
README
README files should contain as much relevant information as possible to allow for the easiest possible experience when setting up setting up an application on a developer’s machine for the first time.
Here’s the default README template when you create a new project in VS Code:
# Introduction
TODO: Give a short introduction of your project.
Let this section explain the objectives or the motivation behind this project.
# Getting Started
TODO: Guide users through getting your code up and running on their own system.
In this section you can talk about:
1. Installation process
2. Software dependencies
3. Latest releases
4. API references
# Build and Test
TODO: Describe and show how to build your code and run the tests.
# Contribute
TODO: Explain how other users and developers can contribute to make your code better.
If you want to learn more about creating good readme files then refer the
following guidelines.
You can also seek inspiration from the below readme files:
- [ASP.NET Core](https://github.com/aspnet/Home)
- [Visual Studio Code](https://github.com/Microsoft/vscode)
- [Chakra Core](https://github.com/Microsoft/ChakraCore)
Here’s a trimmed down version of one for a recent project of mine:
## Introduction
The AppX application generates print jobs for printing on a network Zebra printer after
an SKU barcode is scanned.
AppX is a Progressive Web App (PWA) that is locally installable
on a device and behaves like a native app.
## Repo
https://dev.azure.com/logan/_git/appX
## Developer Setup
Download and install node.js from https://nodejs.org/en (include npm during the install)
Restart VS Code, as the PATH variable changes need a restart.......
## Local Development
To run AppName locally for development, you need to use the following command
from the app root folder:
npx @azure/static-web-apps-cli start --api-location api
## Dependencies
This app sends print jobs to AppZ which transforms the information into ZPL before.....
## DevOps
AppX is hosted on the internal web server \\websrv1.
## Scanner Set-up
Update Honeywell scanner details......
## Application Set-up
On scanner:
1. Google Chrome/Microsoft Edge => Browse to myapps.microsoft.com
2. Login as the user assigned in step 1.
3. Authentication procedure should now ask......
Architecture Decision Records
First introduced in a 2011 blog post by Michael Nygard.
Each ADR is used to record “architecturally significant” decisions made for the project.
What is deemed architecturally significant is up to you, but a few examples are:
- Choice of Object Relational Mapper : Entity Framework vs. NHibernate
- Front-end javascript library : React vs. Angular
- Database : SQL vs. NoSQL
As you can see, these are decisions that are not easily reversed and will dictate how the app is developed.
Each one of the above would have been associated with a separate ADR.
The ADR will contain:
- a description of the requirement necessitating the decision.
- the options considered, their pros and cons.
- the selected option and the reasoning behind its selection.
- positive and negative consequences of the decision
## Localising data for the app
Date: 24/07/2024
## Context
New functionality is being added to App A to replace existing manual process X.
This functionality requires high availability when being used, as the existing
manual process of pen and paper, though slow, has 100% up-time.
This rules out direct communication with unreliable System Z...
A highly-available cloud based data cache will provide the required data with
much lower latency, meeting the performance requirements.
## Considered Options
- Azure Data Table
- Azure Cosmos DB
## Decision
Table Storage was considered first as I was already using it in App B.
Table Storage does not easily cater for types with nested children - specifically,
it does not support IEnumerable or ICollection type properties.
Azure Cosmos DB uses same API and SDK as Table Storage and does allow for complex types.
Complex types are required for this functionality due to the hierarchial format of the data.