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

Richard A. O'Keefe <>
Fri Sep 30 02:04:20 CEST 2016



On 29/09/16 8:11 PM, Vlad Dumitrescu wrote:
> Regarding how Joe is using the docs. How can one provide a static HTML
> that is able to guess
> which mode the user is in right now ('beginner' or 'expert')?

I guess I didn't express myself clearly.
THERE IS NO SUCH MODE.
At ALL times, people are more or less expert about some
things and more or less ignorant about other things.

Even beginners need precise reference material.
Even experts are ignorant of much that is in the
precise reference material.
ALL readers are PART expert PART beginner ALL THE TIME.

(Heck, just a couple of days ago I found something in the
C math library I hadn't known about, and I not only have
copies of all the C standards, I have source for several
C math libraries which I trawl through from time to time.)

If you want dynamic, then one way is to do what I have
suggested about examples and Joe just suggested about
other stuff:
  - you have a very brief "reminder" / "cheat sheet"
    entry per topic
  - you have "reveal details" / "reveal examples" &c
    buttons underneath

At this point I must retract what I said about JavaScript,
which was too harsh.  Hooking the buttons to CSS properties
to support hide/reveal is a great use of JavaScript; one of
the neat things about it is that ALL the material is there
in the page ready for indexing.


More information about the erlang-questions mailing list