[erlang-questions] Erlang documentation -- a modest proposal

[Vlad Dumitrescu]

Hi Joe,

On Fri, Sep 23, 2016 at 12:45 PM, Joe Armstrong <erlang@REDACTED> wrote:

> On Fri, Sep 23, 2016 at 10:23 AM, Vlad Dumitrescu <vladdu55@REDACTED>
> wrote:
> > Hi!
> >
> > On Fri, Sep 23, 2016 at 10:13 AM, Joe Armstrong <erlang@REDACTED>
> wrote:
> >>
> >>  If I see a typo (a simple spelling error) in the on-line documentation
> >>    the barrier of entry for fixing it is HUGE (sorry for SHOUTING).
> >>
> >>    Download the entire distribution - unpack (240 MBytes) find the
> >>    typo (where the heck is it?) - fix it - make a push request ....
> >>
> >>    Do I really have to download hundreds of Megabytes to fix a one
> >>    character typo?
> >
> >
> > Github allows you to make small corrections online, without downloading
> > anything. If you don't already have a fork of the repo, it will be
> created
> > and you will get an option to create a PR for the fix (commiters can
> commit
> > directly to a branch).
>
> Can my dearly beloved wife do this?
>
> Helen is *very* good at spelling and has found many typos in my
> drafts (bless her) - but she's never heard of github - and thinks that
> a fork is something you eat food with ..
>
> > Just go to the file in the source tree and press the "Edit this file"
> button
> > (the pen in the upper right corner).
>
> "Just" - if you can find the file in the source tree that is
>
> /Joe


In your initial comment, you said "If I see a typo", not "if my wife sees a
typo" :-)

I suppose your wife isn't very used to downloading the 240 MBytes,
unpacking them, fixing the file and publishing the change, either. This was
the scenario for which I suggested a simpler alternative.

There is an even better way, actually, even if it still requires a Github
account in its current form. I don't remember where I saw it first, but I
use it for the erlide documentation (which I am well aware that is lacking
in all other respects): each generated page has at the bottom the message
shown below, where the link opens the source file (markdown, in this case)
from which it was generated in the on-line Github editor. This is something
that could be added to the OTP docs too (but hand-editing Docbook XML is
not as much fun as it sounds like :-\ )

> Did you find errors in the documentation? Do you have improvements to
suggest? Suggest edits!
<https://github.com/erlang/erlide_eclipse/edit/master/org.erlide.help/articles/eclipse/250_Editor.md>

best regards,
Vlad



>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160923/b44031fd/attachment.htm>