Documentation Overhaul
The problem
At the moment, the existing documentation (in particular referring to https://eoscta.docs.cern.ch/) suffers from a number of issues:
- A large number of aspects of the CTA system are not documented.
- Parts of the existing documentation are outdated, and it is not clear which parts these are.
- The structure of the current documentation is slightly confusing: sections/subsections are not always logically grouped together and it can be difficult to find exactly what you are looking for.
In addition to this, there are also the cta tape operation docs (https://tapeoperations.docs.cern.ch/), which discuss the aspects of the system that are relevant to internal parties. This documentation appears to also suffer from similar issues. Certain parts of this internal documentation can be moved to the external documentation.
Proposal for Fixing This
At a high level, I propose to do the following:
- Split the documentation into two separate parts: external documentation and internal documentation. The current https://eoscta.docs.cern.ch/ will become the external documentation and https://tapeoperations.docs.cern.ch/ will become the internal documentation.
- Determine what can potentially be moved from the internal docs to the external docs.
- Improve the external and internal docs according to the strategy below.
- Documentation (external and internal) should cover both developer and operations aspects (of course clearly separated where possible)
- A nice to have that would make things a bit cleaner would be to rename
eoscta.docs.cern.ch
tocta.docs.cern.ch
andtapeoperations.docs.cern.ch/
to something likeinternal.cta.docs.ch
. The old domains should ideally remain (at least for a while) and simply redirect to the new ones to prevent potential broken links. This item would be a low priority though; it's just a bit cleaner in my opinion.
The strategy for improving both the external and internal docs would be something along these lines:
-
Define a clear section/subsection layout for the (revamped) documentation. This layout should follow a logical structure:
- Ideally, a novice reader should be able to read it from top to bottom and not have to randomly jump between sections to get an understanding of the system.
- At the same time, it should be clear from the documentation structure in which (sub)section to look if the reader is looking for something specific.
-
Go through the existing documentation and mark irrelevant pages as
deprecated
. These can temporarily be moved to a specific section (e.g.deprecated
). -
Move the information from the non-deprecated files to the new documentation structure.
-
Fill in all the missing documentation and augment/correct the existing documentation where necessary.
We can discuss further in the dev meeting how we are going to approach this exactly and what kind of additional constraints/features we might want to introduce.
The most straightforward first step would be to get a draft going of the structure that we want the external docs to have.
other remarks
- After the updated docs are "finished", it would probably be good to emphasise to anyone using the system, that they should inform us if parts of the documentation are confusing, missing or incorrect. This way we can more easily ensure the completeness and correctness of the docs.
- Another documentation page that could potentially be merged: https://gitlab.cern.ch/cta/cta-operations-utilities/-/wikis/home