What can I say except - wow! I'm a fan since the start (because whatever I
tried I'm too dumb to do current docs). I hope weblate will work out for
translations (given that it seems that only pt_BR is translated on regular
basis currently)

pt., 16 paź 2020 o 19:16 Chris Elston <chris.els...@blueyonder.co.uk>
napisał(a):

> 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
>


-- 
Pozdrawiam,
Hubert Kowalski

___________________________________________________________________________
darktable developer mailing list
to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org

Reply via email to