# Simplifying contributions to documentation

**URL:** <https://discourse.julialang.org/t/simplifying-contributions-to-documentation/7785>\
**Category:** Internals & Design\
**Tags:** proposal, documentation, github\
**Created:** [December 15, 2017, 12:56pm UTC](https://discourse.julialang.org/t/simplifying-contributions-to-documentation/7785 "2017-12-15T12:56:21Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![yakir12](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/yakir12/32/297_2.png) [@yakir12](https://discourse.julialang.org/u/yakir12)\
**Post date:** [December 15, 2017, 12:56pm UTC](https://discourse.julialang.org/t/simplifying-contributions-to-documentation/7785/1 "2017-12-15T12:56:21Z")

</div>

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](https://docs.julialang.org/en/stable/manual/packages/#Documentation-changes-1), suggesting changes to the docstrings of individual functions involves [multiple steps of giting](https://docs.julialang.org/en/stable/manual/packages/#Code-changes-1). 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?

---

<div class="post-metadata">

**Author:** ![nalimilan](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/nalimilan/32/147_2.png) [@nalimilan](https://discourse.julialang.org/u/nalimilan)\
**Post date:** [December 15, 2017, 1:05pm UTC](https://discourse.julialang.org/t/simplifying-contributions-to-documentation/7785/2 "2017-12-15T13:05:56Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![yakir12](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/yakir12/32/297_2.png) [@yakir12](https://discourse.julialang.org/u/yakir12)\
**Post date:** [December 15, 2017, 1:47pm UTC](https://discourse.julialang.org/t/simplifying-contributions-to-documentation/7785/3 "2017-12-15T13:47:13Z")

</div>

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?

---

<div class="post-metadata">

**Author:** ![nalimilan](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/nalimilan/32/147_2.png) [@nalimilan](https://discourse.julialang.org/u/nalimilan)\
**Post date:** [December 15, 2017, 1:55pm UTC](https://discourse.julialang.org/t/simplifying-contributions-to-documentation/7785/4 "2017-12-15T13:55:30Z")

</div>

> [@yakir12](#):
>
> 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?

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.

---

<div class="post-metadata">

**Author:** ![yakir12](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/yakir12/32/297_2.png) [@yakir12](https://discourse.julialang.org/u/yakir12)\
**Post date:** [December 15, 2017, 2:01pm UTC](https://discourse.julialang.org/t/simplifying-contributions-to-documentation/7785/5 "2017-12-15T14:01:03Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![nalimilan](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/nalimilan/32/147_2.png) [@nalimilan](https://discourse.julialang.org/u/nalimilan)\
**Post date:** [December 15, 2017, 2:31pm UTC](https://discourse.julialang.org/t/simplifying-contributions-to-documentation/7785/6 "2017-12-15T14:31:21Z")

</div>

> [@yakir12](#):
>
> I had to first switch branches/tags to master before the pen icon became clickable.

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”).

---

<div class="post-metadata">

**Author:** ![yakir12](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/yakir12/32/297_2.png) [@yakir12](https://discourse.julialang.org/u/yakir12)\
**Post date:** [December 15, 2017, 2:33pm UTC](https://discourse.julialang.org/t/simplifying-contributions-to-documentation/7785/7 "2017-12-15T14:33:07Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![waldyrious](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/waldyrious/32/80_2.png) [@waldyrious](https://discourse.julialang.org/u/waldyrious)\
**Post date:** [December 15, 2017, 5:21pm UTC](https://discourse.julialang.org/t/simplifying-contributions-to-documentation/7785/8 "2017-12-15T17:21:15Z")

</div>

IIUC, [#367](https://github.com/JuliaDocs/Documenter.jl/issues/367) covers what you’re talking about, right?

---

<div class="post-metadata">

**Author:** ![yakir12](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/yakir12/32/297_2.png) [@yakir12](https://discourse.julialang.org/u/yakir12)\
**Post date:** [December 15, 2017, 5:43pm UTC](https://discourse.julialang.org/t/simplifying-contributions-to-documentation/7785/9 "2017-12-15T17:43:28Z")

</div>

Yes!