bit-team
Centralize BiT developer documentation
Current situation
Our documentation for BiT developers exists currently in different locations for different purposes and reasons:
- Contributing - includes how to build
- TOC for developer and maintenance
- Source code "API" documentation (generated from the docstrings)
- user-callback scripts (for debugging and documentation how it works)
- FAQ (Testing & Building)
- ... TODO ...
Proposals
Maintain
- a centralized entry point for all developer documentations links to other documentations
- organize the chapters using developer uses cases (tasks) like building, translation, update API documentation, communication, development process, common Git commands (e.g. around feature branches)...
- ... TODO ...
Open questions
Some chapters may overlap with non-developer use cases, e.g.
- building to install the most-recent version of BiT
- packaging of BiT for different distributions (e.g. required dependencies)
- ...
The documentation should not be duplicated.
Just linking may also be too "invisible" (easy to overlook).
Perhaps markdown sub page inclusion could be a solution to include the full text of an .md file...
Not sure if this is a "Good First Issue" because it needs a lot of internal and deeper knowledge about the development process.
- a centralized entry point for all developer documentations links to other documentations
That was also my goal when creating CONTRIBUTING.md and extract relevant topics for it from README.md. My goal was to make README.md for users (not developers or contributors) and CONTRIBUTING.md for developers. Both files are just landing pages for me and should be short as possible. Short files make it possible for readers to get an overview and decide them self where to dive deeper into (via links). IMHO they are to long for me in the current state.
My approach was to make CONTRIBUTING.md the entry point for potential new contributors who are not familiar with the project and its workflow. Additionally the md-files in the doc-dev folder and the Sphinx generated source code docu is linked there and needed for deeper understanding. To my understanding the doc-dev topics are not relevant for extern contributors but only for the maintainers (us).
Some chapters may overlap with non-developer use cases, e.g.
- building to install the most-recent version of BiT
I don't see it that way. Building and installing are different things. The first for developers the latter for users.
- packaging of BiT for different distributions (e.g. required dependencies)
This is IMHO also mixes developers and users concerns. The README.md don't need a "How to install" section because users are supposed to install BIT from there distro repository. Distro maintainers take care of dependencies. IMHO no need to mention dependencies in the README.md. That is the current situation as far as I can see. Currently having a "How to install" section mentioning Germars PPA and Arch AUR as the alternative sources is a compromise. The section could be shorter and IMHO the maintainers of these alternative sources are responsible to explain on their own landing pages how to use them and installing BIT from it.
Using "make" etc (installing from source) does indicate a build workflow. This all goes to CONTRIBUTE.md.
The documentation should not be duplicated.
Totally agree. I really see no duplicate topics between README and CONTRIBUTING. You found something?
Just linking may also be too "invisible" (easy to overlook).
Yes, this can be improved but depends on who reads. It is not easy to decide.
Perhaps markdown sub page inclusion could be a solution to include the full text of an
.mdfile...
This is possible?
All fair points, I'd see let's put this issue aside for now (low prio) and try to collect more concrete TODOs for the dev doc here...
OK. Also see the need for improvement of the docu but don't have a concrete solution in mind. Most of my modifications of the docu comes from my own use of it. I often use our docu myself. I assume it will improve step by step while the time goes on.
The "user-callback" script docu will be integrated in the manual (see #1659) if our docu migrated to MkDocs (PR #1738).
The rest of the "docu" you list in your initial post is IMHO also in a good shape. But I always try to evaluate if it can be improved while being in contact with fresh contributors asking questions that are not documented or somehow hidden in the docu.
So I think we can close this Issue because it is a bit to "meta".