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
