Documentation structure #485
Replies: 2 comments
-
|
It should be understood what the purpose of documentation is. Code is very granular and time consuming to read and debug through. I should never have to look at the code of a function beyond its definition in order to use it. For a module, the purpose of documentation is to define a module's interface such that the implementation is a black box that the user does not need to look into at all. For a project, the purpose of documentation is so that the user can understand as quickly as possible whether the project solves the user's problems. This means the project has to be immediately usable. It also means the project has to be trustworthy, and trust is built through clear communications. |
Beta Was this translation helpful? Give feedback.
-
|
The |
Beta Was this translation helpful? Give feedback.
-
This thread is about converting https://docs.google.com/document/d/1849cc3kxfqs2-0u9q7YvFg5CGZU445SZu9lIObQHL98/edit#heading=h.m4f1mj64pbc0 to .md files in the repo.
My thoughts are
/docshould be renamed to/docs/docs/adr/- this folder contains architecture design records. Any file using the architecture design document template goes here./docs/api/- this folder contains build scripts to generate the api docs/docs/getting-started.mdthis doc contains information about how to build and run tests, corresponding to section 3 of the google doc/docs/modules.md- this doc contains high level information about each module, corresponding to section 1 of the google doc. Links to each module subdirectory./docs/repo.md- this doc corresponds to section 5 of the google docREADME.mdshould contain the following:Beta Was this translation helpful? Give feedback.
All reactions