[plt-dev] guide vs reference

At Mon, 14 Dec 2009 12:18:12 -0700, Jon Rafkind wrote:
> What is the reason that the guide is separate from the reference?

We tried having one document, and it doesn't work well.

There's a constant tension between explaining everything completely and
providing narrative that hits the high points and flows well. The
reference is or the former, and the guide is for the latter.

> The first two sections of the guide seem like they don't belong in the 
> reference, but every section after 2 has a bit of overlap with the 
> reference.

Yes, that is by design.

> I have some text to update `parameterize' and it looks like the text 
> should go into the guide but I personally almost never read the guide 
> and would prefer it in the reference. [...]
> When I go to look up some function in the PLT 
> manual I usually end up at the reference and just read that. While its 
> true that there are links from the reference to the guide, I usually 
> ignore them (ok my fault) but if I'm going to have to read the reference 
> and the guide they might as well be the same document.

That makes sense. The guide is a kind of read-once document. It gives
you the basic idea and few of the details. Once you understand the
basic idea, the reference is more useful.

> Separating the guide from the 
> reference, even if a good idea logically, only seems to have negative 
> practical ramifications.

Definitely not. A common complaint about the documentation used to be
"the information is there, but I can't see the big picture through all
the details". I rarely hear that complaint any more, at least for
things covered by the guide.

The documentation can always be better at all levels, but separating the
guide from the reference has worked extremely well in practice.

My guess is that you want to add text to the guide, unless it's about
some semantic detail that is not covered already by the reference.