[erlang-questions] Erlang documentation -- a modest proposal
Fri Sep 23 15:21:18 CEST 2016
On Fri, Sep 23, 2016 at 12:45 PM, Joe Armstrong <> wrote:
> On Fri, Sep 23, 2016 at 10:23 AM, Vlad Dumitrescu <>
> > Hi!
> > On Fri, Sep 23, 2016 at 10:13 AM, Joe Armstrong <>
> >> 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
> > and you will get an option to create a PR for the fix (commiters can
> > 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"
> > (the pen in the upper right corner).
> "Just" - if you can find the file in the source tree that is
In your initial comment, you said "If I see a typo", not "if my wife sees a
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!
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the erlang-questions