On Thursday, 7 January 2016 at 13:31:57 UTC, Andrei Alexandrescu wrote:
On 1/6/16 1:54 AM, default0 wrote:
In the end most of this comes down to a lack of motivation: I'm fine trying to improve documentation text if I see an issue about it, but if that entails stopping what I was originally doing for so long that I will possibly forget what I was originally doing (ie requires me to read documentation on how to set up a whole new development environment), I
will usually decide that nah, it isn't THAT important.

Yeah, I empathize a lot. Adam's idea for using web forms for fixes is great.

Here's a simple idea we can implement rather quickly. Say a user is browsing https://dlang.org/builtin.html and find a typo. They press a button labeled "Fix typo". That opens https://github.com/D-Programming-Language/dlang.org/edit/master/builtin.dd. From there people can edit the source file to fix the typo and create a PR, all without leaving the browser or building the documentation.

If this is too heavy-handed, I think Adam's idea of web forms for simple changes is great. We could devise a simple web form in e.g. errata format a la "Replace this" ... "With this".

Would this improve the state of affairs? Creating the "Fix Typo" button is an easy project.


Something along those lines would certainly be very encouraging for making small changes here or there, as it removes much of the learning curve if all I want to do is suggest to change something. That being said, the improvement would be marginal if most of these PRs end up not getting much attention. For instance, if what I'm doing is not fixing a typo but rephrasing two sentences, then the mentality of someone reviewing the PR should not be to simply say yes or no to the change, but to take it as a suggestion that ought to be thought about and possibly improved upon (with or without involvement of the original PR-creator). That is, the line of thinking should be "someone thought what was here originally could be phrased better/wasn't obvious enough about a certain aspect, why and how can we improve it?" given that his rephrasing is not satisfactory or up to quality standards.

All that aside, something small like this while being helpful does not address the issues of the documentation as a whole that Adam is also tackling (layout, navigation, inter-linking(!), pages to explain idioms/commonly used concepts) and having two "official" documentations (one being experimental, I take it) is also less than helpful for navigating around and with regards to these, I would defer to Adams reasoning behind why he chose to not improve on this as opposed to starting over since I am by no means involved enough with this to have my own opinion about how difficult it is to make these types of changes.

Reply via email to