Suggestion for Added Collaboration in Package Documentation

[jackn11]

In my experience, many powerful julia packages are limited by the fact that their documentation is not up to date or is not clear. Users will typically get clarification in discourse rather than specifically making a documentation issue that something was not clear to them.

Furthermore, making suggestions to documentation as a github issue can be time consuming on both ends, and is clunky and unclear.

My suggestion is that something similar to the suggestion mode in google docs be implemented for julia documentation such that any user can make a suggestion in-place (that is to say in the documentation website itself, in a suggestion mode) such as an edit to existing documentation, or add a comment or question.

This would make it much more user-friendly to make edits to documentation, which would help documentation stay up to date.

My second suggestion is with regards to the ease of implementing a documentation suggestion. This step is done by the package owner. My suggestion is, in the same way the documenter package auto-generates documentation from source files, the documenter package should take the documentation suggestions which were accepted by the package owner, and automatically add them to the source code instead of the package owner having to add them to the source code.

This would make julia documentation better and more up to date, and more in tune with user experience, and it would make updating package documentation on the side of the package creator much easier as well.

[mortenpi]

I agree with the sentiment and I think it would be awesome to have something like this, but it's a little non-trivial. Here are some of my unorganized thoughts:

• One thing that has been on my mind for a long time that I think could be useful is to have a way for users to post comments on manual pages (inspired by the "User contributed notes" in the PHP documentation). So, basically, I imagine each page having a comments section somewhere. Another way to also implement this would be to allow the readers to highlight some text and attach a comment to that.

• The edit suggestion feature is a little different, but I think has similar goals, and the implementation would be similar.

• Either of them would require a backend server. Documenter ultimately is a static site generator and doesn't have any server anywhere to store any data. Search is another example where a backend server could make our life in some ways easier (and search faster).

• Building and running a special backend for e.g. the Julia manual would be relatively doable. However, making it available for any package author adds a whole other layer of complexity (unless we ask everyone to self-host it on some cloud service).

• The source files for the documentation are kept in Git repositories. So the part where the system would "add the suggestions to the source code", would probably have to be something that just opens a PR against the repo.

• This would be a relatively complex thing to implement, since it has quite a lot of parts to it (needs a UI in Documenter, outside of Documenter for package owners, and a backend, interaction with GitHub for suggestions etc.). I personally do not foresee having the bandwith to tackle something like this any time soon.

• However, if there are people out there who would like to implement something like this, I think this could be made to work as a plugin package (the bits that would have to live in Documenter would basically be just some JS, and shouldn't require very extensive modification of Documenter itself, just hooking into it here and there).

[fredrikekre]

Might be nice to make it easy to enable https://utteranc.es/ (see e.g. https://franklinjl.org/extras/utterances/) so people can comment using Github logins.

[mortenpi]

I didn't know about utterances. It looks really neat and solves most, if not all, the difficult parts. For the backend, I was imagining you'd have to authenticate anyway, probably via GitHub OAuth.

I wonder if it would be possible to modify it to use Discussions instead of Issues... (edit: utterance/utterances#324 and there is also https://giscus.app/).

[mortenpi]

Note: #1412 is closely related. But the OP here seems to be more about including edit features directly in the Documenter-generated HTML. I'm not sure how feasible that actually is (theoretically, probably, but it's a lot of backend and front-end work; which is why some utterances/giscus-type solution is probably the best we could hope for).

But we can leave this open as a speculative feature request.

[odow]

My 2c: I think we should close this in favor of #1412. There is already an edit button in the top-right, and we've discussed improving the documentation to make it easier for contributors.