You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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.
edoc
and create TEIs to describe what it’s actually like right now create an example project as an addtion to the documentation #231TODO: before picking this up, create sub-issues for these items!
The text was updated successfully, but these errors were encountered: