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

On 1/7/16 2:14 AM, Rory McGuire via Digitalmars-d-announce wrote:
> I wonder; would it be possible to make the website inline editable and
> then it automatically creates github pull requests that update the docs
> in github as D comments?

Ha. I just posted about that! -- Andrei

On 07.01.2016 14:31, Andrei Alexandrescu wrote:
> 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.

We have this already. Top right corner, "Improve this page". People are using the feature occasionally.

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.

On 1/7/16 8:38 AM, anonymous wrote:
> On 07.01.2016 14:31, Andrei Alexandrescu wrote:
>> 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.
>
> We have this already. Top right corner, "Improve this page". People are
> using the feature occasionally.

Yes, in fact, core developers use this too.

It's actually quite a bit more convenient than doing stuff locally.

-Steve

On Thursday, 7 January 2016 at 06:30:28 UTC, Rory McGuire wrote:
> If not a tagging system then at least adding synonyms would be great.

dpldocs.info actually had this in its first version, way back in 2010, because so many people would ask me these kinds of things.

In the first draft, I did it as a separate database. In the new one, I will add a "Tags:" section to my ddoc parser that will figure them all out. The search engine will use it definitely, and perhaps the See Also referencer too, though I'm not sure about how that'd look. I need to flesh things out a bit more.

I'm also thinking about adding a "category" thing too but submodules or aggregates in the source code are usually better there, so I'll probably stop at tags.


In the ddoc source code, the section would look like:

/++
    Some explanation

    See_Also:
        * $(REF indexOf)
        * $(REF findSplit)
    Tags: contains, in
+/
.... canFind()...


That is, the tags is just a comma-separated list of keywords in the source.

On 01/07/2016 09:05 AM, Steven Schveighoffer wrote:
> On 1/7/16 8:38 AM, anonymous wrote:
>> On 07.01.2016 14:31, Andrei Alexandrescu wrote:
>>> 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.
>>
>> We have this already. Top right corner, "Improve this page". People are
>> using the feature occasionally.
>
> Yes, in fact, core developers use this too.
>
> It's actually quite a bit more convenient than doing stuff locally.

Ah, sorry. I knew "Improve this page" existed but thought it goes through a more elaborate process. Shame on me I didn't bother to try it before posting...

Would it be a good idea to make that button more prominent?


Andrei

On Thursday, 7 January 2016 at 13:38:20 UTC, anonymous wrote:
> We have this already. Top right corner, "Improve this page". People are using the feature occasionally.

My first experience with this:

1) Seems to work well enough initially, if you can do without a preview.

2) Then the request comes to rebase to stable [1]. There is no web interface for that, so I followed friendly instructions from the reviewer and created a new PR by hand by clicking through github and redoing the changes. Not so smooth but doable if you have been on github before.

3) Then the PR needs to be rebased again because of merge conflicts, introduced by another PR [2]. Reluctant to close the PR and correcting the mistakes a third time in a new PR, I decided to download a local clone and merge locally. Git not being part of my daily routines, that was as smooth as I feared it would be (not at all).

Fixing these small documentation errors took more than an hour of my time. I just hope the PR can be merged before it needs rebasing again ;-)

[1] https://github.com/D-Programming-Language/phobos/pull/3907
[2] https://github.com/D-Programming-Language/phobos/pull/3908

Bastiaan.

On Thursday, 7 January 2016 at 14:05:27 UTC, Steven Schveighoffer wrote:
> On 1/7/16 8:38 AM, anonymous wrote:
>> On 07.01.2016 14:31, Andrei Alexandrescu wrote:
>>> 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.
>>
>> We have this already. Top right corner, "Improve this page". People are
>> using the feature occasionally.
>
> Yes, in fact, core developers use this too.
>
> It's actually quite a bit more convenient than doing stuff locally.
>
> -Steve

I'm a D user and forum lurker, not a contributor. I have used this feature several times in the past and it was seamless and easy each time. For small typos/one-liners it takes <5 minutes to edit changes and submit the PR.

Cheers,
lobo

On 08.01.2016 00:13, Bastiaan Veelo wrote:
> My first experience with this:
[...]
> Fixing these small documentation errors took more than an hour of my
> time. I just hope the PR can be merged before it needs rebasing again ;-)

The master plan here is to get you invested in D. You just spent a non-trivial amount of time on improving it. You may think that has been annoying, but at the same time you don't want to see the effort go to waste. You want D to succeed now. You're one of us now. One of us. One of us. ;)

More seriously, maybe someone more experienced should just take over in such cases. I think people don't do that, because
* it's not common practice,
* they have more than enough on their plate already,
* they want to encourage the newbie to become familiar with the system so that they'll be able to make larger contributions in the future,
* they don't want to steal the newbie's credit,
* they'd have to wait for another staff member to review it while they can just pull it themselves when the newbie perseveres (not sure if that one's accurate).

But you can totally say that it's too much trouble for you, and that you'd like someone else to take over, of course.

Also, a tip: After rebasing, leave a message stating that you did. Reviewers are not notified of rebases by GitHub.