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.
Andrei
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.
