This is just a template.
You may not need every aspect of the template, but they give you an idea what can be documented in your projects.
Good documentation reflect any granularity of your project.
This snippets extract a list of directories.
ls -dl /home/darius/*/ | awk -F'[[:space:]]' '{print $NF}'Please apply general best practice for software development.
path is the path that you want to list the content of
List of directories
number is the number to process.
heavy number computations
For general installation guide, see the general documentation. For this project you need java 11 that be installed via homebrew:
brew install java@11set DEBUG=1 to enable debugging.
place a debug.conf file in the project root for setting up the database settings.
The credentials for accessing the servers can be found in the credentials repository
- IP / Host
- Password
- Cert
- CA
The ssh key can be found in Secrets
You can access the production server via the Jumphost on 127.0.0.1.
ssh -i key.pem -N -L 8156:127.0.0.1:8156 [email protected]How deployment is triggered?
Deployment is triggered after every main commit via jenkins.
How tests need to be executed?
Tests are executed for each open Pull Request / Merge Request via jenkins.
Some FAQ for the application.
- What business problem should be solved?
Try to convert them to functional requirements where possible. For example, instead of fast, write: "The application needs to answer in 10ms"
Who are the stakeholders and how to reach them?
What kind of data is collected or processed and what data privacy regularization need to be taken into account?
What Frameworks are used?
- Why this architecture was selected?
- What design where discusses but not selected and why?
Maybe you can add a nice diagram using puml how its working?
- What monitoring is applied for the service and what metrics are most important?
The service is returning some amount of errors. What to do in this case?
The service stopped working at night (for example terminated). What to do in this case?
How is responsible for provisioning / updating the underlying hardware?
How is responsible for security of the application and the operating system with their dependencies?
What step is done before and after this applications finish? How is the data handed over to the next team?
This section now describe information that are relevant for external Partners.
In case you are providing a public api you can document a lot!
How to get access as user?
Where to send test calls?
Do you provide a public swagger documentation for the users?
How does the data model look like?
- Keys and values with their types.
- Keys and values with their types.
What is returned in case of errors? What errors are can be returned by the API?
Description of how to use the software in case you have some frontend. How about a video that shows the usage of the software?
When you provide libraries or any other artifacts that can be included by the user, describe how to do it. Ideally create a minimal repository with an example.
Documentation have to be taken care. Update it as often as possible.