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

Reply via email to