Requirements for Documentation

[JanCBrammer]

We have identified the following minimum requirements for our documentation.

1. There should be specific docs for each version of the ELN

• This is important especially w.r.t. installation instructions, since they have changed considerably throughout versions.
• Legacy docs (i.e., not current version) won't be maintained and only receive critical updates (e.g., security)

2. We need to be able to edit the docs such that changes can be (selectively) made across different versions

- For example, if a change in v3 is benefecial to and also valid for v2 (but not v1), then it should be possible to only apply the changes to v2 and v3.

3. Users should be able to conveniently edit the current version of the docs

- How to ensure that non-functional edits (typos, style) to one version are propagated to other versions?

• How to ensure that we do not clutter our git history with a bunch of minor edits?

4. Developers should be able to conveniently document (new) features

• Ideally, we would like documenting and feature-development as closely coupled as possible.

5. Docs should be available offline

• The offline docs would pertain only to the version that's currently running in the offline environment.
• There should be a way to access the same documentation even if the ELN fails to run i.e. for troubleshooting scenarios.

6. Other related services need to be documented alongside the ELN

• For example, we currently we need documentation for Repo, LabIMotion, ChemSpectra, CLI and ChemScanner.
• We need to figure out how (and if) to integrate the documentation of these services into existing docs.

7. Provide roles for different types of readers of the docs

• Structure docs along the lines of roles, such that it's easier for readers to find what matters to them:
  • developers
  • users
  • admins
  • contributors

🚀 CALL TO ACTION 🚀
Please add additional requirements, remarks and/or suggest solutions as comments on this issue. When proposing solution(s), please clarify how the solution fulfills the above requirements. @harivyasi and I will integrate your contributions in the list above.

[JanCBrammer]

4. Developers should be able to conveniently document (new) features

• Ideally, we would like documenting and feature-development as closely coupled as possible.

@harivyasi, and @ptrxyz suggest to host the ELN docs in the ELN repository https://github.com/ComPlat/chemotion_ELN) to make the docs more accessible / present (increased likelihood of being updated), and easier to version (docs would simply follow versioning of ELN).

[JanCBrammer]

5. Docs should be available offline

• The offline docs would pertain only to the version that's currently running in the offline environment.
• There should be a way to access the same documentation even if the ELN fails to run i.e. for troubleshooting scenarios.

@fbroda suggests distributing PDF or HTML docs with an ELN instance.

[NRayya]

4. Developers should be able to conveniently document (new) features

* Ideally, we would like documenting and feature-development as closely coupled as possible.

It is understandable that developers give higher priority to developing, but one solution could be to agree to open a documentation issue as soon as new feature implementation starts. At least one can keep record of what needs to be documented. Then maybe documentation hackathons dealing with the open issues can solve the problem (one day every month?)