Non-friendly documentation

I think that reducing the barrier for contributions is a (the ?) major topic here.

I often wish I could make comments directly in a (documentation) page (ideally in a WYSIWIG way like you can comment a pdf or a google doc) while I am reading it. These comments can be either typos, or indication that a given sentence is really difficult to understand, or that a given term is not (yet) defined, or an entire copy/pasted Julia MWE.

Obviously, PRs are greats but they are only natural and easy for (experienced) package developers. End-users will rarely take the time for this. Git hub “issues” are far easier but are not WYSIWIG and you have to take additional time to specify what and where you find unclear/wrong in a documentation.

This would require to develop an appropriate dynamic web app for documentation but this large piece of work could be used by all packages and amortized by the community (as well as the server infrastructure). If you consider a tool similar to shared google documents, where you can “accept” comments, it could be also a good way to merge this kind of instantaneous PRs via a simple click.

This involves more work from the package maintainer than proper PRs but I guess that a lot of them would be happy to have more feed-back anyway.

7 Likes