Simplifying contributions to documentation

Internals & Design
, ,
1

Is there any way we can simplify the way users can contribute to the documentation of packages? While changes to the README.md file are easy, suggesting changes to the docstrings of individual functions involves multiple steps of giting. While many of us (especially me) should improve our git-fu, I suspect that the future Julia (v1.0 AD) users would be put off helping by that hurdle, especially if the contribution is small (just a few words in the docstring of one function).

So is there any way we can lift that hurdle somehow?

1 Like
2

Actually, you can edit documentation files on GitHub, and Documenter-generated online manuals provide a link to do so at the top of every page.

3 Likes
3

Those don’t allow you to edit the function’s docstrings, just the content in the help files. So if you define a function in your package and include a docstring, then that can’t get edited directly from github. Or am I wrong?

4

It’s slightly less obvious, but you can browse the file on GitHub and click on the small pen in the top-right corner to open a PR online. In Documenter-generated manuals, the source link for a docstring will point you directly to the relevant source file.

2 Likes
5

Awesome!
I had to first switch branches/tags to master before the pen icon became clickable. But now it works! Thanks for the tip.

6

Indeed. Probably worth filing an issue against Documenter: it could be useful to provide two links, one to the relevant commit (the only way to be sure the contents match), and one to the file on the master branch (which could be labelled e.g. “edit file”).

2 Likes
7

(would you mind doing that? I don’t feel confident enough to argue about git stuff in an issue)

8

IIUC, #367 covers what you’re talking about, right?

2 Likes
9

Yes!