[erlang-questions] Erlang documentation -- a modest proposal
Lutz Behnke
lutz.behnke@REDACTED
Fri Sep 23 13:39:05 CEST 2016
Arrrgg! What have I done?
Joe, please _do_not_ install Eclipse. It will lead you down a path of
pain and the acceptance of continued unexpected behavoir in a bloated
monster! You where rightly horrified and are likely to still be.
Unfortunately it is the only IDE that a) has support for all the
languages that I have to converse in concurrently and b) has pretty
buttons to help me rember how to activate specific functions.
If you start with a new tool I would advise something more lightweight.
Atom looks good, but I do not have the time to invest in learning a new IDE.
+1 (at least) on the low barrier comment think.
mfg lutz
Am 23.09.2016 um 12:51 schrieb Joe Armstrong:
> On Fri, Sep 23, 2016 at 10:36 AM, Lutz Behnke
> <lutz.behnke@REDACTED> wrote:
>> 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
>> list).
>>
>> 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 -
>
> /Joe
>
>
>> 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
>
> /Joe
>
>>
>> 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
>>> suggestions.
>>>
>>> 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
>>> unpacked)
>>>
>>> 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:
>>>
>>> http://www.latextemplates.com/template/the-legrand-orange-book
>>>
>>> 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
>>> of
>>> erlang - it would be nice to browse your own code, clicking on function
>>> names
>>> 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
>>> like
>>> interface.
>>>
>>> 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
>>> always
>>> 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
>>> beings
>>> 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
>>> https://en.wikipedia.org/wiki/Widows_and_orphans)
>>>
>>> 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
>>> documentation.
>>>
>>>
>>> 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"
>>> http://book.realworldhaskell.org/read/functional-programming.html
>>>
>>> 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
>>> fixes
>>> 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
>>> great.
>>> [the problem is to find the XML that needs to be edited, given that the
>>> error
>>> 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
>>> content
>>> 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 <essen@REDACTED> 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
>>>> some
>>>> practice; and that's when a good function reference with all details and
>>>> examples is helpful.
>>>>
>>>>
>>>> --
>>>> Loïc Hoguin
>>>> http://ninenines.eu
>>>> Author of The Erlanger Playbook,
>>>> A book about software development using Erlang
>>>> _______________________________________________
>>>> erlang-questions mailing list
>>>> erlang-questions@REDACTED
>>>> http://erlang.org/mailman/listinfo/erlang-questions
>>>
>>> _______________________________________________
>>> erlang-questions mailing list
>>> erlang-questions@REDACTED
>>> http://erlang.org/mailman/listinfo/erlang-questions
>>>
>>
>> --
>> Lutz Behnke
>> Hochschule für Angewandte Wissenschaften Hamburg,
>> Labor für Allgemeine Informatik,
>>
>> phone: +49 40 42875-8156 mailto:lutz.behnke@REDACTED
>> fax : +49 40 2803770 http://users.informatik.haw-hamburg.de/~sage
>> Berliner Tor 7, 20099 Hamburg, Germany
>>
>> _______________________________________________
>> erlang-questions mailing list
>> erlang-questions@REDACTED
>> http://erlang.org/mailman/listinfo/erlang-questions
--
Lutz Behnke
Hochschule für Angewandte Wissenschaften Hamburg,
Labor für Allgemeine Informatik,
phone: +49 40 42875-8156 mailto:lutz.behnke@REDACTED
fax : +49 40 2803770 http://users.informatik.haw-hamburg.de/~sage
Berliner Tor 7, 20099 Hamburg, Germany
More information about the erlang-questions
mailing list