Documentation question

[Alan Pinstein]

I want to have the best documentation possible to make it easy for
people to use PHOCOA.

The documentation needs to achieve many purposes, yet I also want to
keep it as compact as possible (for ease of use and ease of creation).

This is a request about the non-API docs, as the API docs are always
be available since they are auto-gen'd from source comments.

Here's what the docs should provide:
1) Conceptual explanations of all aspects of the system
2) Real-world examples (as opposed to the simplest possible case)
3) Best-practices for common scenarios
4) Consistency of examples
5) Actual working examples (as opposed to just code in a document)

Is there anything else?

I am thinking that I want to extend the Blog example in the
screencast and current user guide to a full-blown application to
demonstrate all aspects of the system. I could even include the Blog
code with phocoa, or as an easily-accessible extra download. This way
people could actually run the system that is documented.

I am shying away from providing the blog download app as a set of
"steps" as is often seen in some tutorials, since that can take a
very long time to do. Although, I suppose I could try to stick that
in SVN and tag or branch things...

Anyway, please let me know what thoughts you have about this so I can
be sure to direct my efforts in a way that is most useful.

Thanks,
Alan