I think , there are two barriers for users making better docs:
- Prior experience required to work with doc-tools (Documenter.jl, what else?), examples, tests and so on.
- A number of user actions (N) needed to be done in order to contribute into a package doc. Optimally,
N <= 3: open input form – wirite or paste text – confirm.
To address #1, there should be simple videos like “how to improve docs in 5 minutes?”, similar to this.
To address #2, there should be some simplified tools that automate making proposals to the docs, based on user actual behaviour when he or she tries to fix errors or learns new packages. Usually I learn new packages into separate .jl files and then use them along with reference docs, when I need to remember or reuse something.
So, there are too many actions needed to convert some jl scripts – into an approved PR. How it is done now:
- Make a local copy of a package in dev.
- Make a separate branch.
- Find where docs are generated, add new examples.
- Check if they look OK.
- Cover docs examples with tests.
- Make a PR.
- Fix some problems with that PR.
…What else did I miss?
Hypothetical shortest paths (one or two simple actions required from user):
a. Automatically convert discourse solved questions into FAQ examples attached to packages? Or just have a list of links at the end of the docs.
b. Add some user-input form, embedded into docs, so user can just copy-and-paste his proposals and code in arbitrary place, then convert it to an automatic PR. Just like sidenotes: “nope, this is not working, better use this: …”, that can be added into main text.