Documenting unreleased features in the guide

[markd at macports.org]

>at the moment, we do not distinguish between features in the released
>version and features on trunk only (e.g. universal_archs, sort
>master_sites by ping) in our guide. This will easily lead to confusion
>by users. Therefore we need some way to ensure users get the right
>documentation and do not make wrong assumptions because they read about
>stuff which is only in trunk. Also, stuff on trunk might change until it
>is finally released.

I think a more pressing problem that contributes to this problem is that
we have no formal way of saying "here's a new feature that needs
documenting".  I think we need a document that mirrors "Changelog" that
lists new features that will effect documentation.  Right now we can
create tickets, but I don't think this is used too much.  I squirrel away
links to base changes that I see on the list for future documentation, but
sometimes I miss them, as I did for the new fetch feature.  So frankly,
since I think keeping documentation up-to-date is a higher priority than
that worrying that users may try to use a feature, and when I feel lucky
to discover by pure chance a new feature, as it happened this time, I've
just wanted to get it in writing before the moment is gone.

All that to say, simply that I think we need something comprehensive like
a "ChangeLog docs edition" before a concern that users will be confused by
unimplemented features in the guide can really be addressed.  That said,
the point you make is completely valid of course.
>
>I think there are multiple ways to deal with this problem. Here are two
>different solutions:
>
>1) Branch the guide to the release branch
>This means multiple trees of the guide exist. While new features are
>being documented on trunk, fixes to the existing documentation are
>merged back to the release branch. Might lead into some work to do the
>nominating and merging stuff.
>
>2) Include version information directly in the guide
>There is still only one tree of the guide. Every new feature and
>variable documented has a version number. This will just be a smaller
>printed information after the variable name or below the section
>headline, something like ">=1.7.0" or "HEAD only".
>
>I already had some words about this on IRC with Joshua and Bill (who
>actually suggested number 2). Personally, my first idea was way 1, but
>after some thinking I like way 2 better. As our guide is always
>work-in-progress, I think this will be a good way to reflect the current
>state how things work according to the version information.
>
>Other ideas? 

I think two branches of the released guide is cumbersome.  And though I
don't like including version numbers in the guide per se, but I'll throw
out another alternative that is sort of a "third way" betwen 1 and 2.  Use
DocBook "profiling"; some vendors refer to this feature as "conditional
text".  So the xml in the guide that represents features in HEAD are
flagged as such, and two guides are cranked out by the stylesheets.  So we
would in fact have two versions of the guide as far as generated html, one
for the released version and one for HEAD, though only one source tree. 
But as I said, I think we'd need to get a handle on listing base changes
that need documenting before this would really work.

Mark