Ideas about documenting enough for non-library projects.
The aim of this document is to give rules to follow in order to make a project understandable from a producer and consumer point of view. The idea is to have a simple setup where code self-documents itself whenever possible. When this is not possible we will give options on how to go about it.
The documentation should start at the repository's README.
Regardless if we then create a static site to host the documentation or we decide to use github's wiki, the repository's README should point to the right place.
- setup: how to install the used stack, package manager, build tools, environments setup and how to get the credentials
- scripts: how to build, test, run and deploy the application for the different environments
- service: how is the application exposed to the public: REST, UI, etc.
- source code: how does the code itself reads and how easy is to follow the repository's changes
- manual tests: how to setup specific tests that need to be done manually (by cookie, query param, header, etc.)
Let's elaborate a bit this points.
To document how to setup the environment we just need to make sure to specify how to install the different libraries necessary to build, test and run the project. To document this we can list the stack we are using followed by pointers to install these dependencies
- Docker
- {Language}
- {Build tool}
- {Framework}
- {Database}
- {Credentials} (using
keybaseorcredstash) - Any other big dependencies that you think worth to mention
Once this is done we should be able to find out information about these depependencies and how to use them.
Along with the setup there are some scripts to start a server, local database, or build the source code for deployment. These scripts might also need some additional knowledge of the project which might get complicated.
As a workaround for this situation one could use a common tool to run this scripts such as make. Each of these scripts then can be as complicated as needed underneath.
All right, we have the application running. What does it expose?
If exposes information through REST.
Considered solutions:
- RAML https://raml.org/
- Swagger https://swagger.io/
The simplest is swagger.
Motivation to choose swagger:
- Postman can import swagger files
- Supports Open API spec 3 (article)
- https://apimatic.io/transformer (transforms API description formats)
The front-end spec is tighly coupled with the designs. Recent developments on this area point to sketch and zeplin as good options.
This means that the documention in the frontend is done by testing against designs. A solution for this could be niffy. The rationale here is that the designs are a big part of the front-end documentation thus, we have to make sure to align with them or the designs are not.
Source code is enforced by the producers and reviewers. Other than the source code itself (which is also documentation), if we want to create a document that will explain it, we can have either a comprehensive document (taking in consideration all of the details and then we have to maintain it) or a descriptive overview acompanied with a hands on example.
Like this one:
- Comprehensive would be what we expect of a library (each method on the API is documented, a book)
- Descriptive is what we draw to show architechture designs (relationships between entities, changelog and a diagram)
Because being comprehensive needs more resources for maintain it one can argue that if we tag changes on the repository accordingly is easy to have a changelog (out of git log). If one needs more elaborated an architecture diagram accompanied with an example should do it.
The architecture diagram explains the source code design. The example shows how one would use the application (a feature, a bug). Plus: both changelog and diagrams are easy to maintain.
Besides of the above, what we have left of is code comments which has to be done by maintainers and enforced by reviewrs. Its on their hands to decide where comments are necessary and make the code understandable for the future.
When we have to setup the state of the application (already running) to do a specific test manually. It can be either a stress test, performance tests, A/B tests through cookie, query string, etc. Normally they can be automated and included on our tests suites but, if it really has to be done manually at this point in time, it would be tricky to find out.
Which means:
- We should document this manual tests to keep an eye of the edge cases and look to automate them in the future.