Re: [oll-user] Learning manuals vs. reference documentation | lilydoc

[Urs L. <ul...@op...>]

Am 05.04.2013 17:33, schrieb Urs Liska:
> As Joe pointed out my conception of openLilyLib's documentation could
> make our lives unnecessarily complicated.
I should have included the following:
> Urs:
> > There will be one 'book' documenting OLLib. This is traditional
> > documentation.
> > And there will be tutorials that are made accessible on the web site.
> > They aren't conceptually related to OLLib, although they may of course
> > use it and may dwell on certain aspects of it.
> >
> > Is that clearer?
> Joe:
> It's clearer but I also think you have alternatives that are worth considering.
>   Consider e.g. how D documents its standard library:
> http://dlang.org/phobos/
>
> Each function/data structure in the library has a brief piece of documentation,
> including examples, that is closely coupled to the source code (in fact it is
> written in the source code next to the code it documents, and the documentation
> is automatically collated from these doc entries in a manner similar to Doxygen).
>
> This is nice and easy to maintain because it is trivial to make sure the small
> amount of documentation associated with a given function is up to date with the
> function implementation itself.
>
> It's imperfect in another way, because it gives you a only case-by-case
> documentation that is not so well integrated as (say) a book.  But it also means
> you have a fundamental resource to point people towards which is fairly well
> guaranteed to be accurate.
>
> That in turn gives you a certain amount of freedom with respect to other more
> "user-friendly" documentation such as an in-depth manual or tutorials, because
> there's slightly less urgency behind their being 100% up to date and accurate --
> they can be_a_  reference, not THE reference
>