[erlang-questions] Erlang as a tool for human communication -- was GUI development

[Joe Armstrong]

I agree!

(with what you ask?)

I could write a lot about this ...

The model of documentation I would like to see is:

   - One author many eyes

Note this is not the wiki model - I like articles that are opinionated
and represent
a clear point of view - I may or may not agree with that point of
view, but I like there to be a clear point of view - books are written
by individual authors not committees and I like this.

Many eyes is great for fixing bugs and fact checking - so it should be
easy to comment on the document, but only the author can make the
changes.

   - Beautiful output

The result should be pleasing to the eye and in multiple formats
(epub, html and PDF)

This is *impossible* (I think) with markdown - markdown solves the
wrong problem.
Markdown solves the problem "make the input simple" it does not solve
the problem
"make the output beautiful"

LaTeX solves the problem "make the output beautiful" - but the input is a mess.
XSL + Apache FOP makes the input parsable but beautiful output is *challenging*

  - Easy to organise the input

OK - the output should be beautiful - the input might be a mess (if In
LaTeX) - but moving chapter headings around etc and cross indexing etc
should be easy.

I have no good solution to this. My current attempt at this is to use
emacs org mode
for organisation. Then have embedded XML, and inside the XML and special tag
<md> ... </md> for embedded markdown (actually not the real markdown,
but my own variant)

  - Low barrier for entry to comments

 If a reader is reading the text and sees a spelling error, correcting
it should be one
mouse click away. The Erlang documentation requires you to git clone everything
fix the source and send a pull request. This is crazy and will scare
off many users.

The best system I have ever seen for this is in the real-world haskell site
Go check out http://book.realworldhaskell.org/read/ - pretend you have
seen a spelling
mistake and see how easy it is to fix it.

  - Parseable document tree

I'm a great fan of having well-structured input that is parseable with
a strict grammar. This
is so we can build complex documents. This seems to rule out markdown and LaTeX.

My only solution to this XML - but *not* docbook (which is far too complex)

 - Extensible

  I want plugins to generate diagrams, color code etc.

Combining these different requirements (beautiful output, etc.) is
very difficult
and I have seen no free system that can do all these things.

There are great tool chains available - for example when I wrote my Erlang book
the pragmatic press provided a tool chain.

The input was XML (Yes XML) - I have absolutely no problems with this,
most of my time
was spent in thinking up good examples and wording of paragraphs not typing in
tags.

The stages involved were

    - authoring
    - editing (this was chapter by chapter with an editor providing feedback)
    - beta release (publish a PDF - this is the many eyes bit)
    - final chapters and more editing
    - proof reading
    - final edit
    - indexing
    - layout

The author/editor part is interesting - this is not *many eyes* - each
book has an editor
who helps the author a lot (actually teaches them to write decent English)

Any automated system should have provision to automate the feedback cycles
author/editor and author/readers.

One more thing I forgot - who is your audience and what do they know.

Syncing with your audience is essential - If your book is 20 chapters
you need to write say
5 chapters, then try them out on your target audience to get the level
right and adjust the level *before* you write the next 15 chapters.

This is also true for a 10 page document.

I think the problem we have to solve here is one of making a documentation
*system* and not producing individual papers.

Short articles with ugly output is easy in markdown - but an entire system with
thousands of pages of text needs a lot of complex organisation.

I'd actually love to know how a newspaper solves this - a decent newspaper
turns out tens of thousands of words per day - news articles are
written, proof read and edited in hours - commissioned articles are
integrated with the news and there must be hundreds to thousands of
contributing sources.

The software behind these systems is not open source and I haven't a
clue what it costs
or who produces it - is it in house or purchased?

I guess things of the scale of a magazine are done with adobe's indesign.

So we a spectrum of documents.

     - simple documents (markdown)
     ....
     - magazines (in-design)
     - books (proprietary)
     ...
     - newspaper (proprietary)

Where do we want to be positioned here? My guess is something 'book
like' is better than what we have today - but not commercial book
quality.

Cheers

/Joe





On Fri, Dec 22, 2017 at 7:03 AM, Lloyd R. Prentice
<lloyd@REDACTED> wrote:
> Hello,
>
> This is a think piece that may run longer than prudent for this forum. But
> if not here, then where? It is motivated by the recent thread re: GUI
> development and various other threads re: Erlang documentation. It asks
> serious questions that may or may not be worthy of reflection and discussion
> across the Erlang community.
>
> Here's a little about me, not to toot my horn, but to clarify where I'm
> coming from.
>
> I've been striving to become reasonably proficient in Erlang for nearly four
> years now. I come with experience in software development, but in no way
> consider myself a professional programmer. My undergraduate education is in
> English language/liberal arts with a focus on creative writing;
> communication and national development was my focus in grad school. I was
> for seven years on the full-time faculty at Boston University's School for
> Public Communication. I was founding editor/publisher of Classroom Computer
> News, one of the first magazines focused on personal computers in the K-12
> classroom. My company. Prentice Associates Incorporated developed more than
> 100 shrink-wrapped educational/consumer software products for leading U.S.
> publishers. My company also developed a major web application for marketing
> and managing world-class IT conferences Among other things, I write fiction;
> have three novels in print.  I could go on, but you get the picture.
>
> I come to Erlang with a vision of a web community devoted to helping indie
> authors/publishers write and market better books. I was attracted by the
> reliability/scalability promise of Erlang. But it's been a hard slog
> learning Erlang and bringing my vision to fruition, taking far longer than I
> would have hoped, leavened only by the generous help from many members of
> this community.
>
> At this point, my understanding is that Erlang is a terrific language for
> distributed back-end systems and, to some extent, scalable web applications.
> But my sense is that the Erlang community is smaller than the merits of the
> language deserves, has an aging community and, rather than organic growth,
> seems to be fragmenting into a cluster of BEAM languages that don't, from
> what I've seen, bring much vitality back to Erlang OTP.
>
> The question I've asked myself over recent months is, "Why doesn't Erlang
> have more libraries supporting human communication with the same
> effectiveness with which it supports machine-to-machine communication?"
>
> The recent thread GUI development thread is Exhibit Number One.
>
> The various stalemated Erlang-questions threads on Erlang documentation is
> Exhibit Number Two.
>
> Loïc Hoguin has done some nice work on documentation tools. I do wish they
> were more widely used and, themselves, better documented.
>
> This makes me wonder why we don't eat our own dog food, that is, develop and
> adopt standardized documentation tools written in Erlang and fluent across
> all media?
>
> Wings3D is, from what I've read, an effective 3D CAD system. But I don't
> hear much about it or see how it's libraries or components are of value to
> the Erlang community. Perhaps there are hidden jewels in the Wings3D code
> that could support GUI development.
>
> Joe Armstrong has been experimenting with music production. I love to see
> more documentation of his work. Can his work be extended to broader audio
> applications?
>
> A few folks have been working with video streaming. Wouldn't it be great to
> see tutorials and well-documented open source libraries and tools.
>
> Erlang Nitrogen goes a long way toward easing the pains of web development.
> But it could go much further with broader support. These days, poor Jesse
> Gumm is just about it.
>
> I'm not sure what's going on with Chicago Boss. That seems to be on Jesse's
> shoulders as well.
>
> The content management framework Zotonic is terrific in every dimension. But
> you have to move out of Erlang and to hop across several syntactic
> boundaries to use it. Mark Worrell has been talking for some time about
> "Elastic Zotonic," e.g. distributed Zotonic. Is he thinking Riak? I don't
> know, but wouldn't that be cool.
>
> I've been pulling my hair out over the past year trying to bend erlguten,
> the not-well-documented six-year-old library for generating PDF documents,
> to my needs. It's a gem in the rough that could provide the basis for a
> powerful suite of print and digital media production tools.
>
> Just today I learned that erlguten has been maintained and in production at
> Klarna and that within the past year Richard Carlsson has released a
> MIT-licensed "canonical" version on GitHub. Yippee!
>
> https://github.com/richcarl/erlguten
>
> Richard's road map is dead congruent with what I've been trying to
> accomplish in support of Writersglen, the project that has absorbed my
> nearly every waking thought over the past half decade.
>
> Many of the things that I want to do in Writersglen could be accomplished in
> other languages and with tools and applications written in those languages.
> But I want to work in Erlang. I don't see any technical obstacles to
> building better human communication libraries and tools in Erlang.
> Selfishly, I don't have enough years ahead to learn other languages. I want
> to build my web community. I want to build it in Erlang. And I wish I'd been
> able to launch it two years ago.
>
> But beyond my own interests, my hypothesis is this: With more
> well-documented and polished open source libraries and applications focused
> on human communication, Erlang would attract a wider, more diverse,
> population of programmers and developers. This, in turn, would result in a
> more vibrant community and wider adoption of Erlang.
>
> Am I wrong?
>
> If not, what can we do to make it happen?
>
> Perhaps the problem is that we don't have an appropriate venue or forum for
> sharing ideas.
>
> All the best and happy holidays,
>
> Lloyd
>
> Sent from my iPad
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions
>