Identify good examples of User Guide/Programming book organization

[oubiwann]

As we begin to iterate on the LFE docs, we need to think about the content we want to present to various types of end user, how that content should be organized, what content is missing from existing docs that would be nice to add, and what content we should remove or rework.

@bigos shared the following link:

• https://en.wikibooks.org/wiki/Haskell

And this is a great example of organizing content by experience level. It's not a very common approach, but I like it -- especially for an online resource.

We should also map out the topics covered in:

• Learn You Some Erlang
• Programming Erlang
• Erlang Programming
• Designing for Scalability with Erlang/OTP

Then, after compiling that list, we could divide the topics up across one or more levels of experience, as the Haskel wiki book has done...

At any rate, if you have a favorite programming book, please provide a link in the comments and why you liked it, and if you have the time, why you think LFE would benefit from something like that.

Thanks!

Part of the Planning Epic.

[oubiwann]

Tangentially related: using gitbook might be a possibility, especially if it will work with the same markdown used to generate the site: https://github.com/GitbookIO/gitbook

[oubiwann]

Some Lisp Books:

• Lisp Outside the Box (toc, CC chapters)
• On Lisp

[oubiwann]

This topic is now being covered in a series of tickets filed here:

• https://github.com/lfe/user-guide/issues

I will keep this ticket open for now, but it will eventually be closed in favor of the repo and it's tickets linked in this comment.

[oubiwann]

More books:

• Common Lisp the Language, 2nd Edition
• How to Design Programs, Second Edition - Creative Commons
• Casting SPELs in Lisp - GNU Free Documentation License 1.2

[oubiwann]

Racket docs are pretty much award-winning:

• http://docs.racket-lang.org/

[oubiwann]

So the thing that I have been using the most over the past year to generate user guides for my LFE projects is actually Slate. While I can't say I love it, it's provided enough of what I need for me not to have to build something from scratch.

That being said, here are the warts that I've found most awkward so far:

• Splitting narrative description / prose into one column and code examples with explanation into another column. This works well when you have to support multiple languages simultaneously ... and to be fair, that's exactly what Slate is targeted at. It doesn't work so well when there's just one language ... it comes of rather stilted and forced.
• The fact that it's generated by Ruby :-/ It'd be nice to use the language that's actually being written about.
• ToC no working correctly for bottom sections that don't have much content (see Solve the bottom-of-the-page bug slatedocs/slate#280).
• The generated docs are everything-in-a-single-page

http://readme.io has a similar feature to Slate:

• https://sample-threes.readme.io/v1.0/docs

They also provide a version that uses integrated content instead of split out into columns:

• https://sample-solid.readme.io/docs/ordersid-2

It's also not single-paged, which I tend to prefer.

I'll probably keep using Slate for now, but as soon as I've got time to tackle a User-Guide-in-a-Box for LFE projects, I'll give Slate up in a New York second and start using the Other Thing.

[yurrriq]

After lfe/lfe#211 is closed, the compiler will help us out a lot. Then I'll also be able to port the topics feature from Codox and document how other people can write a Lodox writer. Maybe even codify that into a behaviour.

[oubiwann]

No doubt :-)

But!

Like the other ticket, the context of this ticket is very high-level. Think "technical books" and "tables of contents" ...

The stuff that lodox will do will help with individual projects that are written in LFE, but again, this ticket is discussing a different matter -- user guides and books vs. API references ...

[oubiwann]

Going to call this one too -- but everyone should feel free to update as ideas occur!