Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation overhaul #572

Open
4 tasks
dariok opened this issue Dec 19, 2024 · 0 comments
Open
4 tasks

Documentation overhaul #572

dariok opened this issue Dec 19, 2024 · 0 comments
Milestone

Comments

@dariok
Copy link
Owner

dariok commented Dec 19, 2024

Frankly, our documentation is a mess and in parts severely outdated.

Updating the wiki is not complicated but often forgotten. Also, it is not really the best place for a specific documentation as it might contains info for a completely different version of wdb+.
The idea to have a DITA based documentation within wdb+ was good but either precompiling that into HTML or including a complicated set of transformations to create HTML does not make maintenance any easier.

Hence, we should create a documentation in TEI that is included within the release itself and thus readable on the server. It is, basically, a type of project in its own right and does not really need any special treatment.
It should, though, be placed outside of data and thus some special handling is necessary as the usual ID-path-retrieval mechanisms might not work without some fiddling.

This means that we need to really always update the documentation when we introduce relevant changes – but hopefully that is easier done when it is up to date and within the same repo.

Also, this should not only be a tech doc for admins, but also include the important information for users – how and what to do, expect, etc.

  • create a new collection within edoc and create TEIs to describe what it’s actually like right now create an example project as an addtion to the documentation #231
  • tests to ensure that displaying everything works
  • (oh, by the way: that can then be used to create automated tests related to displaying stuff as they will always be present in the DB → mocha)
  • include a link to the documentation / help on all pages

TODO: before picking this up, create sub-issues for these items!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant