Introduction
Both the Specifications and the implementation sub-projects in Anuket have documentation produced in different style and different templates. The structure of the final documentation is not well designed and calls for rethink on how the documentation is organized. This requires a team which feels responsible for the different pieces of documentation and works for a consistent representation of them in the overall Anuket documentation.
Responsibilities
The documentation working group would responsible for:
- General look and feel for Anuket documentation, both of the implementation sub-projects and the specifications.
- Toolchain for rendering the documentation
- Documentation guidelines and implementation of linting rules
- Advisory role on information modelling and documentation ideas flow
The documentation team would not be responsible for:
- The technical content of the documentation except for the documentation guide. It is the sub-projects responsibility to provide the technical content of the documentation.
- Proofreading of the documents
- Making major edits to documentation workflows
The Documentation team should be responsible for the following parts of the documentation:
- https://docs.anuket.io landing page of Anuket (docs folder in https://gerrit.opnfv.org/gerrit/opnfvdocs )
- https://cntt.readthedocs.io landing page of Anuket specifications (doc folder in https://github.com/cntt-n/CNTT)
- https://github.com/cntt-n/CNTT landing page of the Anuket specifications repo (root folder of https://github.com/cntt-n/CNTT)
- Documentation building framework for the Anuket specifications (tox,ini, conf.py _static, _templates files and folders in the folders of the documents in the Anuket specifications and in Anuket sub-projects) in a collaboration with the different sub-project contributors
- Documentation building framework and support of Anuket implementation projects in a collaboration with the different sub-project contributors
- https://docs.anuket.io/en/stable-kali/how-to-use-docs/ Documentation guide for Anuket
Committers
Meeting details
- Re-using the unused time slots of the Weekly Technical Meeting
Task management
- Use GitHub and a separate GitHub project under the CNTT repository
Action Items
- Take the proposal to the TSC to discuss.
- Update/refresh the existing CNTT guidelines
Comments about the proposal
Cedric Ollivier This presentation is fully unclear and looks like an overseed of activities done by other contributors.
The documentation build framework is already in place and follows the classical opensource practices in place in ONAP, ODL, etc. All the changes done in Anuket are already shared with ONAP doc PTL.
The current model based on PR works and I would rather suggest a global LFN initiative as discussed in ONAP and now in TAC.
Look and feel of Anuket documentation is rather in charge of LFN (html part) and GSMA (pdf part). Idealy on community side, it's just one or 2 lines in 8 conf.py files ... 5 min work.
Yes,
- proofreading must be an action for all contributors in CNTT (see the first release plannings). It shouldn't be set in a specific project.
- technical content is about the stream itself
My recommendations would be to focus here on the CNTT files (gov, field trials, etc.) not tracked by any existing stream and which are currently obsolete ; to TSC to care about who is doing what especially about doc.
If we need a room to discuss latest sphinx/rst proposals, RA1 has been the main Anuket room. We could use Weekly technical discuss if we stop cancelling it and if we stop conflicting our meetings.
Last but not least this proposal cannot work anywhere else than Github CNTT because there is only one tree. In ONAP (or any Anuket software project) it fails by design you must go to the patch set as the existing model before this proposal.
Any monolithic project would de facto fail.