[erlang-questions] Erlang documentation -- a modest proposal
Fri Sep 23 12:51:29 CEST 2016
On Fri, Sep 23, 2016 at 10:36 AM, Lutz Behnke
> I would propose a position specific to the reference documentation:
> 8) Put the documentation in the source code. Use edoc (or similar new tool).
> This would not take a step in the direction of
> https://en.wikipedia.org/wiki/Literate_programming (which I think is a type
> of holy grail that stiving for is good, but reaching will not really help),
> but also put pressure on edoc to improve the presentation (pos 2 in Joe's
> But it would also help when the documentation is not sufficient to provide
> understanding: first you can look at the documentation website. Should that
> fail to provide understanding to the user, he or she has a clear system of
> going from docs for module X to source of module X and looking there. Much
> more daunting, but a clear escalation path. Also just grepping for phrases
> from the documentation is quick and to the point.
> And it should a precedent for 3rd party libraries. Java doc/ Doxygen are
> fairly good examples for wide spread adoption or integration into other
> tools. And it helps me write docs when I can still remember what the func
> actually does.
> Other Point: Joe, getting the OTP code drop from github is not a problem at
> all. one copy and paste on github website, two clicks in eclipse. Voila:
> manual work done.
Uuugh - I have to install and learn how to use Eclipse
I have to know what github is.
The wikipedia has a low barrier for entry - if you see a spelling
mistake on a web page fixing it should be as easy as right clicking
the mouse on the word
typing a correction and hitting "send"
I tried Eclipse once and was horrified -
> BTW: This does not contradict your point on user-comments on the docs
> website. php.net was pointed out in this discussion before. The best code
> examples there are in the user comments.
So make it drop dead easy to add comments - no sign in - no github
no eclipse - no build system - no emacs - no vi - no source code tree
Just point - click - add
> mfg lutz
> Am 23.09.2016 um 10:13 schrieb Joe Armstrong:
>> I have a few comments about the documentation:
>> This answers a few question that keep arising, and has a few of my own
>> Q: Who was the documentation written for?
>> A: Ericsson Internal usage
>> The original documentation made the following assumptions
>> - The readers would be internal Ericsson programmers who knew Erlang
>> - If the programmers had a problem understanding things they would ask
>> us directly
>> So we favored a terse declarative style
>> Q: How is the documentation structured
>> A: It's all in XML
>> The idea was that all documentation would be generated from the XML
>> There are current about 1000 XML files containing about 10MB of text
>> The XML sources are in the distribution source tree.
>> So for example the documentation for lists.erl is in the file
>> <Dir>/lib/stdlib/doc/src/lists.xml (<Dir> is where the system was
>> Q: How is the documentation produced
>> A: Programmatically
>> Various programs munge the XML inputs (and the sources) trying to make
>> web-sites and PDF
>> We could use some help here - really - the PDF is produced with
>> some XSLT magic
>> and the web site with goodness knows what.
>> So what's wrong and what could we do?
>> 1) Things are not beautiful
>> I agree - the documentation is not typographically beautiful
>> Personally I like PDF - I took a look and found this:
>> It would be nice to transform the documentation into this form
>> for printing and reading
>> 2) The HTML documentation could be improved and made more interactive
>> I have at various times written 'erl_to_html' that makes HTML pages out
>> erlang - it would be nice to browse your own code, clicking on function
>> to follow the code or to unfold the documentation.
>> On-line documentation can have things like type spec in hidden folds
>> which open in place when you click on them. Or possibly a tiddly-wiki
>> http://tiddlywiki.com/ might inspire a new interface
>> 3) There is no official proof-reading quality control mechanism
>> I tried on several occasions to hire a technical author - management
>> views this as a waste of money - so this never happened.
>> Most of the documentation is written by people who are not
>> native English speakers. They could use some help.
>> By contract my Erlang book had
>> - Me (who wrote it)
>> - Dave Thomas (my editor) (he was great)
>> - A Proof Reader (By proof reader I mead one of these super-human
>> who can spot a spelling error at 10,000 meters from your text,
>> while reading upside down by candle light
>> - An Indexer (did you know there were professional Indexers?)
>> - A typographer (who worried about
>> Have you every heard *anybody* complaining about widows and orphans
>> in the Erlang printed documentation? I had to rephrase several
>> paragraphs to avoid nasty widows and orphans.
>> 4) There are no examples
>> I agree there should be zillions of examples.
>> Rather than adding them to the existing XML tree I'd propose a new
>> DTD for examples which could be cross-linked into the
>> 5) There are no construction examples
>> Examples show "the finished work" but not "how you got there"
>> In my book I often shown really short functions in 10 lines or so
>> of code. But I don't discuss how I got to those ten lines.
>> I show the 10 lines and explain what each lines does.
>> I do not explain how I wrote the first line - I might have googled
>> a bit done some research. In a 50 line program I'll probably have
>> tested it as I grew it - testing 10 lines at a time.
>> How we grow programs from small seeds is not explained.
>> 6) The barrier for entry for fixing a typo is HUGE
>> 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?
>> I keep pointing people to the web site for "real world Haskell"
>> The barrier for entry to fixing a mistake in the text is minimal.
>> I actually like the RWH model - the reader adds a comment, the author
>> the bug.
>> When writing books I would not like other people fixing my typos, I
>> want many eyes to help be find the typos - then I'll fix them? Why
>> is this? Because I'm ultimately responsible for what I write -
>> Sometimes (not often) I might want to totally rewrite a section
>> based on a single typo.
>> If somebody could figure out how to automate fixing typos it would be
>> [the problem is to find the XML that needs to be edited, given that the
>> was found in a generated document - I guess if each paragraph has
>> a hidden GUID
>> <<WHICH I'VE BEEN RANTING ON ABOUT FOR YEARS>> it would be trivial]
>> <aside>All paragraphs should have GUIDs and be stored in a global
>> adressable store (why GUIDs? - we could use the SHA as a key but
>> they we could not
>> edit the paragraph :-) </aside>
>> 7) The erlang mailing list has loads of examples
>> The erlang mailing list has thousands of useful examples
>> but they are not extracted, edited sorted and classified.
>> There are issues of copyright and attribution here - but I think
>> it would be useful to extract some of the better postings to this list
>> and move them into the documentation tree.
>> Making beautiful readable useful documentation is very difficult and
>> needs love care and attention to detail - it's an unappreciated form
>> of literature.
>> On Fri, Sep 23, 2016 at 8:40 AM, Loïc Hoguin <> wrote:
>>> On 09/23/2016 05:18 AM, Kenneth Lakin wrote:
>>>> Speaking of the User's Guide... -ideally- someone with no Erlang
>>>> experience should first be reading the Reference Manual User's Guide
>>>> along with the Getting Started Guide (or LYSE or something) to pick up
>>>> the fundamentals, rather than the various module Reference Manuals. In
>>>> my experience, reference manuals exist to quickly provide useful
>>>> information to people who are already familiar with a language. They
>>>> shouldn't be language primers, as primers serve another purpose and
>>>> should be in another document.
>>> That's the thing: you have no control over what document people will read
>>> first. You also have no control over what people will *remember*.
>>> When first coming to the language, most people will
>>> forget/misremember/misunderstand most of what they read until they get
>>> practice; and that's when a good function reference with all details and
>>> examples is helpful.
>>> Loïc Hoguin
>>> Author of The Erlanger Playbook,
>>> A book about software development using Erlang
>>> erlang-questions mailing list
>> erlang-questions mailing list
> Lutz Behnke
> Hochschule für Angewandte Wissenschaften Hamburg,
> Labor für Allgemeine Informatik,
> phone: +49 40 42875-8156 mailto:
> fax : +49 40 2803770 http://users.informatik.haw-hamburg.de/~sage
> Berliner Tor 7, 20099 Hamburg, Germany
> erlang-questions mailing list
More information about the erlang-questions