Introducing dtdocs (https://github.com/elstoc/dtdocs)…
This project is a complete rewrite of the darktable documentation in
markdown, providing a number of advantages over the current user manual:
* *simple markup*: The current documentation uses complex and highly
brittle xml markup which is very hard to maintain and is a
significant impediment to developers documenting new and amended
features. The markup to content ratio is unreasonably high (approx
40% of it is markup) and the effort required to make that markup
legible is, unless you have an editor designed for it, tiresome.
Markdown uses minimal markup allowing developers to concentrate on
getting the content right. Hopefully this will encourage more people
to contribute to the documentation. If nothing else, new content can
be lifted fairly easily from the OP of new pull requests.
* *familiar*: Github issues and PRs are written in markdown meaning
that the learning curve for creating markdown content is very low
* *portable*: With the exception of the yaml metadata headers (which
are pretty standard in static site generators such as jekyll, hugo,
and pelican) this documentation is written in pure markdown. While
it is currently intended to be rendered in the hugo static site
generator (SSG), it should be trivial to port it into any other
markdown-based SSG, and to render it to ebook formats using the same
content. This also has the advantage that most of the content (and
rich diffs) render well in github, including links and images (with
the exception of some unsupported markdown extensions).
* *easy to build*: The current manual relies on a complex set of tools
and is often difficult for users to build and test. Using hugo for
web rendering (a single binary) makes it trivial for developers to
quickly view their changes on a local version of the website.
* *fewer images*: Images should be included in the user manual only
when they aid understanding of non-standard functionality or
concepts. This makes future maintenance simpler as we don’t need to
redo the images every time the darktable interface changes. Many
images (especially those that just show a collection of basic named
bauhaus controls) have therefore been removed.
* *simplified and improved content*: While the content is largely
based on the current user manual, it has been thoroughly reviewed,
copy-edited (so that the content reads better in English) and
re-ordered where necessary to improve clarity. Extra content has
been written to better explain some of the more complicated aspects
of darktable. Finally, guides and examples have been moved to
separate sections (rather than sitting alongside module
definitions). This allows us to better document and group ‘how to’
guides for operations where multiple techniques are available (e.g.
sharpening, monochrome). This work is still in progress.
* *separate repo*: Our hope is that this project will eventually be
migrated into a separate repository alongside the darktable and
dtorg projects. Keeping the documentation separate is particularly
useful because it allows the documentation to run on a slightly
different schedule to the main darktable project (it doesn’t have to
freeze just because a release has been frozen) but the intention is
that it would be released at the same version numbers as darktable
(when those versions are ready). This also allows less technical
authors to be project maintainers without them also being
maintainers on the main darktable repository.
This version of the user manual is currently up-to-date (in terms of
content) with the latest changes in darktable 3.4, including recent user
manual updates. However, work is not yet complete. Here’s a short list
of our current ToDo items
* Translation workflow – the current intention is to use Weblate and
we’re hoping we can reuse some of the pre-existing translations
* Website style and layout is still being finalised
* pdf and epub versions are still WIP
* The Guides and Tutorials section will mostly be new content and is
awaiting authors
* The auto-built Lua API manual is currently out of scope
* Other things we haven’t thought of yet
While the language has been fully reviewed to make it read better in
English, it’s highly likely that errors have been introduced or that
rewording has changed the intended meaning and mis-stated some of the
actual darktable functionality.
So what we need now is reviewers – both from a technical point of view
and to help ensure that the manual is as clear and unambiguous as
possible. We also welcome any other comments or suggestions that you may
have. The manual source is currently hosted at
https://github.com/elstoc/dtdocs(published to
https://elstoc.github.io/dtdocs/). Please feel free to raise issues on
the Github project or submit pull requests if you think anything could
be improved.
Kind Regards,
Chris Elston (@elstoc)
Mica Semrick (@paperdigits)
___________________________________________________________________________
darktable developer mailing list
to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
