Better docs for D (WIP)

default0 via Digitalmars-d-announce digitalmars-d-announce at puremagic.com
Thu Jan 7 05:52:32 PST 2016


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.


More information about the Digitalmars-d-announce mailing list