Document all code with README files
Description
Click to expand
Who
- @janaina.senna @kabir.kbr -- guidelines for writing README-X.md files;
- @janaina.senna -- assign tasks to developers to update documentation based on the repository / module on which they are working;
- @kabir.kbr -- support and explanation as needed of the automated documentation system based on the work done so far;
- cc:/ @0xPravar @joao.castro5 @sam.lake @avimanyu786 @umair-nunet
What
- Our aim is to build an automated documentation system resulting in living documentation which is tightly related to the development process and results in [technical] documentation that is always up to date; The motto of 'living documentation' is that documentation is seen as part of the code, and is built within the same pipeline (almost);
- The solution for this is to build documentation directly from the repositories (or, rather, README files that are included in each module in the codebase) and describes all;
How
- EVERY repo, module, etc that has code also needs to have a description for that code;
- README-DEV file contains technical descriptions for developers, therefore most probably will be more present;
- README.md contains user-oriented descriptions, and it could be that it will not be needed on each module, which are technical. Each repo should contain both developer and user documentation. Preferably each module should contain developer documentation. The need for user documentation for each module should be determined by the owner/maintainer of the code on case-to-case basis;
- As a result of the #23 (comment 1555488965), all Public Alpha repositories were [over]populated by the readme files as described above. As a result of this issue, these files will be provided with content or deleted if not needed.
- If README.md file is not present in the module / repo, the respective living documentation portal will not be built for that module.
Why
The documentation is super important (and living documentation is the yet-best-known-way-to-do-it), for:
- Sharing the technical context and details among developers in the long term (internal, external, etc.)
- Providing full information of the platform operation to external auditors that are auditing Public Alpha;
- Building a framework towards allowing external partners to integrate NuNet into their business processes / applications, without (almost) efforts from the core dev team; This is as important for the scalability and usage potential of the Public Alpha as the code itself;
When
- Based on the results of #23 (comment 1320213086)
Acceptance Criteria
Click to expand
- Guidelines for README.md (user documentation) done;
- Guildeines for README-DEV.md (technical documenation) done;
- Each repository assigned to a developer and timelines set;
- The automatic documentation system is adapted as needed;
- Update of files needed for documentation is included into acceptance criteria of each issue -- from now on.
Work Breakdown Structure (WBS)
Task | Description | Duration | Status | Start Date | End Date | Comment |
---|---|---|---|---|---|---|
A | x Hrs | Done/In Progress |
Edited by kabir