Identify good examples of User Guide/Programming book organization about docs HOT 9 CLOSED

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 ...

from docs.

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

from docs.

Some Lisp Books:

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

from docs.

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.

from docs.

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

from docs.

Racket docs are pretty much award-winning:

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

from docs.

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 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.

from docs.

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.

from docs.

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

from docs.