Bad news: as of now, the documentation will not be up to date for the coming 5.0 release of darktable (they probably won’t even be up to date for the current 4.8 release…).
We’re asking for help writing up new features! If we can get some people each spending a few hours to document a feature, that’d put a huge dent in things (or even have everything documented!).
Your English doesn’t need to be perfect nor do your technical writing skills. Just get some words down!
Steps to helping with the documentation:
!. We suggest testing on a spare computer if you can. If you don’t have spare computer to test on, we suggest making backs and, if possible, setting different locations by launching darktable from the command line.
2. Get a recent build of darktable from here and install it.
3. Log in or register a github.com account.
4. To find a list of features or changes that need documentation, see this list.
5. Pick an item off that list, open darktable, and determine if the documentation needs an update. If the PR doesn’t require a docs update, please leave a comment on the PR asking to remove the documentation-pending label. If the PR does require a docs update, then document the feature and submit a PR to the dtdocs repo. Please note which PR you’re documenting.
It is a worthwhile exercise as it really makes you understand the changes/improvements in darktable. However, I feel unsure about the best format to supply the new document as. I submitted a word document hoping this would be fine for the reviewers.
I will share the advice @elstoc gave as it may be helpful to others.
It’s usually easier for us to directly see what you’ve changed and be able to post our own edits – a pull request is usually the best way to do this. If you can’t face learning how to do this locally with the git command line, you can also do at least an initial edit directly in the github web interface.
Simply go to the relevant file in this repository (start here and then navigate through the sections as you would the website to locate the file you want to change). Click the “Edit” button and make your changes and when you’re done click the “commit” button and select “Create a branch and start a pull request”.
I’d like to also mention that we’d prefer people learn the “proper” process for making and submitting pull requests (which means forking the repository, making changes locally and then using the git command line to create and submit changes – there are plenty of guides online) as I believe it gets harder to make subsequent alterations if we suggest changes using the web interface. But the github web interface does at least make the learning curve a little less steep.
And we’d still very much prefer to get initial drafts from developers.
I’d be happy to help out with this. The only thing is, I’ve not used darktable — for no other reason than RawTherapee takes care of everything for me. Now, however, I have the ideal chance to check it out.
I may, therefore, be a little slow off the mark, but I’ll definately get involved.
I’m not sure how to resolve this, so I’ll just mention it here and see if anyone has any ideas. One of the biggest problems I have with reviewing pull requests for the documentation is checking for factual accuracy. I’m very reluctant to merge things that I can’t verify (from the code) or demonstrate (through use). Anything you can do in a pull request to make it easier to check accuracy (especially when recommending “how to use” a module) will make it much more likely that a request gets merged quickly.
This is one of the reasons we really like the developer who wrote a feature to do the first draft, since I’m much more likely to take their suggestion as authoritative, without the need to thoroughly check.
What about changing the order at least for the cases where the developers struggle to write the documentation, e.g. because it’s hard to find the time to do it right? Now that @paperdigits opened pandora’s box anyway with the call for contributions, why not let users write the draft and have the developers check them? That could make the documentation work on developer side easier because you can start with a draft version and do not have to start from scratch, and at the same time, the factual accuracy is not harmed if the particular developer fine-tunes the user’s draft.
At least I find it helpful to not start from scratch when I have to document something, because sometimes I struggle to find a good structure and a reasonable starting point. Even if the draft is totally nonsense, it kick-starts my brain to think about the topic and come up with a solution.
At the moment, developers choosing to write documentation is very much the exception rather than the rule. It’s hard to know why developers don’t/won’t do this. We thought spending 6 months transferring the documents to markdown format would make it easier for developers to submit documentation, but it seems that wasn’t enough of a motivation.
This would be fine with me, though the onus should be on the author (of the documentation) to do this. In this case, the process should be:
Identify the pull request requiring documentation (from the list mentioned by @paperdigits in the first post).
Write a draft and submit it as a pull request to dtdocs
Put a link to the documentation PR in the darktable PR and tag the developer asking them to review it.
At the moment I am having a hard time getting to the end of step 2, due to a combination of time and motivation.
I am a user of darktable but know nothing about code etc
I have spent 20 mins trying to work out how to update documentation but the instructions are not very easy for me to follow. I see someone did it in word and that wasn’t liked. Would it be possible for someone to do a very short 5 min youtube video just showing how to do it in the way you want please?
That may be impossible to do within 5 min… It might help if you could indicate which part is a problem.
If it is the requested formatting, just google “markdown”, you’ll get more than enough to get you started.
In short, it’s a plain text format with special items being marked (1-3 ‘#’ for titles and subtitles, etc.).
Very simple to use for text, it allows inclusion of files and hyperlinks. Simple text editors like Kate, Vim, notepad are enough to write markdown text (“*-Office” suites are not really suitable, though).
Wrt. word documents being rejected: the instruction ask explicitly for markdown formatted text.
While instructions for authors may seem arbitrary sometimes, there are reasons for such instructions, and in other domains, it’s normal for submissions to be summarily rejected if they do not follow those instructions. Trying to get them in proper shape takes a lot of time for the editors, much more than the author would have spent following the instructions in the first place… At least here, there’s nothing exoctic in the instructions.
I’m trying to gently persuade people to do as much of the work as possible in the documentation and in most cases people are willing to give it a try. I don’t mind tidying up someone’s work or even updating the documentation myself if people really can’t get their heads around the pull request process. But there comes a point where the amount of effort required from me is more than if I did all the work myself, and at that point I will insist (or just ignore the work submitted and make my own independent submission). In that case, it was less about the format (MS Word) than that it was unclear which page was being updated, or which words had been added/removed, and the user did indeed submit a PR, which was more helpful.
Certainly if the user is going to submit more contributions to the documentation, my having to repeatedly do most of the work would become tiresome for me.
In general the instructions for submitting pull requests are standard git/github processes, which are well documented in many places. I’m reluctant to include my own version of those instructions in the repository or individual bug reports because again, what I’m trying to achieve here is for the documentation work to be spread out amongst more contributors.
If people are intending to make continued contributions to the documentation, I don’t mind providing some assistance the first time. Please join us on the IRC/matrix chat and ask for help (see contact | darktable).
I totally get that you guys put vast amount of hours into this project for the benefit of others which is appreciated. I think if you want to spread the load further, spending time on really high quality and uber simple instructions on what you want newbies to do might be a pain in the short term but would save time in the long term.
If you are just a user of darktable you have no idea what ‘standard git/github processes’ are.
I have now seen a reply to the initial post which advises one goes to the relevant file in this repository (start here and then navigate through the sections as you would the website to locate the file you want to change). Click the “Edit” button and make your changes and when you’re done click the “commit” button and select “Create a branch and start a pull request”.
I will try and follow that. A 2 min video that someone can follow showing that would probably get you a lot more volunteers
For simple edits, the web interface works pretty good.
Tips, always save your commits to a new branch in your fork. Then push (aka send) your commit (aka your saved edits) to the main repository as a PR (aka change request).
Before doing future edits, start by pulling (aka receive) commits from the main repo so you have the latest version of the files.
Sadly, it didn’t work that way.