Documentation and where we put it

Community Feedback
1

Hey Community,

while thinking about 2.0, something occurred to me:

Where do we want to put our documentation? Currently everything resides in the main repo as until a few months ago there really was only one. Now we have at least two repos and possibly more in the future, which require some documentation, it seems to me we should think about how we do documenatation in the future.

  1. Where do all Repos keep their documentation? How is it put together?
    a. Keep everything in the hedgedoc/hedgedoc repo
    This would make it easy to keep everything put together at all times, but necessitates multiple PRs to change a feature and update it’s documentation, which in general is not very desirable as stuff can come out of sync or even be forgotten.
    b. Keep documentation in a separate hedgedoc/docs repo
    This seems to be not much different than a as it has the same problems, but instead of nearly all repos, all repos have the “our documentation is in another castle” problem.
    c. Keep specific documentation in the corresponding repos. Add general guides and multi-repo documentation to a hedgedoc/docs repo
    This seems to be most desirable as everything is in the correct place generally speaking. Of course we would need to have extra PRs to change the API spec and such if they live in a separate docs repo, but that would be the case in a or b too and e.g API changes need to be addressed in multiple repos anyhow. This leaves the question where such documentation should be presented?
    One place I thought of was readthedocs.org. I think we could use them to gather our documentation (multiple repos seem to be supported via subprojects) and make it a more pleasant experience to read them. Also multiple versions of documentation are suppored, which we should take advantage of not only for 2.0 and 2.1, but 1.7 as well. This make the old documentation accessible to people, when we switch to 2.0.

  2. Improve the documentation
    I think it would be great to improve the documentation for 2.0 (not sure it’ll help to much for 1.7 nor if we have enough man power to do that in addition to 2.0).
    Some months ago @sheogorath mentioned this talk by Daniele Procida at PyCon Australia 2017 in the chat. There is also this blog post and the Django documentation as an example. The structure they propose is shown in this graphic:
    grafik

Tutroials

Guides to get you started step-by-step

  • learning by doing
  • getting started
  • inspiring confidence
  • repeatability
  • immediate sense of achievement
  • concreteness, not abstraction
  • minimum necessary explanation
  • no distractions
  • needs to be bulletproof. Anyone should be able to complete these

How-To Guides

Guides to solve one specific problem

  • a series of steps
  • a focus on the goal
  • addressing a specific question e.g “How to setup LDAP-Auth”
  • no unnecessary explanation
  • a little flexibility
  • practical usability
  • good naming

Discussions

explanations

  • giving context
  • explaining why
  • multiple examples, alternative approaches
  • marking connections
  • no instruction or technical description

Reference

descriptions of classes, APIs and such

  • structure
  • consistency
  • description
  • accuracy

I propose to structure our documentation in this way.

What do you think?

2

I just played around a bit and at least the subproject option doesn’t seem to be right for us. I guess our best approach would be to have the docs folder in all the two repos and a separate docs repo. If the default branch of any of the repos get’s new commits, a CI job is run on docs, which fetches those changes builds the docs and commits if anything changed. That way the whole documentation lies in the docs repo to be fetched and build by readthedocs and the actual changes can be made in each repository with the actual code changes.

3

To be honest I don’t like that idea of having docs in two different places and mirror them over. CI jobs can break, and then things get out of sync again, people create PRs in different places etc.
From the options listed in the first post I favor option b - keeping documentation in a separate repository. If I look at the topic from the perspective of an end-user/administrator, I would like to have all the docs in one place and not in x different places.

4

Where should the sources live?

Keep the docs in the code repos. The documentation should be tied to the implementation it describes. You can also split the type of docs very well.
e.g. “How can I do this XYZ in the frontend?” => frontend
“How do I set up the software?” => backend/admin

How should the docs be generated?

If the docs live in the code repos, then we could add a repo with a CI that runs every hour. It would collect the docs from the repos and generate one output. This output can be pushed to RTD or github pages.

5

HedgeDoc is one product consisting of a backend and a frontend. Technically one could exchange the frontend with another one, but in the end it’s one project.

Currently, the source code is divided into the react-client (frontend) repo and the hedgedoc (backend) repo because both stages of development are that disjunct that it wouldn’t make sense to combine them.

In the future, we could discuss whether such a merge back into one repo (which has its own set of advantages and disadvantages) should be done.

Regarding the question of the docs - finally I’m getting on topic - I propose the following:

  • We wait with the question about where the docs should be finally stored until we’re in the stage of combining frontend and backend (however that’s done).
  • The 1.7 documentation stays in the backend-repo as it was already until now.
  • A temporary documentation-repo may be created, in which a new documentation for 2.0 can be developed until we discuss the topic again as remarked in the first point.
1 Like
6

I think this sounds very reasonable @ErikMichelson