On Jun 13, 2005, at 8:46 AM, Ralph Goers wrote:
Sylvain Wallez wrote:
Same concerns as Ugo. We should IMO document 2.1 and use specially
labelled sections and pages for what's different in 2.2. We could
also uses Daisy branches, but I don't think it's a good idea to
start a multi-branch effort right now.
I agree with this also.
I know how slowly I can work sometimes, so 2.2 is a good target for
me. ;-) I think what we want is to have current documentation. When
2.2 is released we want to be ready. We don't want to go back and
update documentation that we have just finished, especially if we
could have incorporated it as we went along. Likewise I don't see us
ignoring 2.1, since no one in there right mind would ever use the
latest relaease :-O. We can't document anything that doesn't exist
yet, but we do have to work with the latest versions in order to stay
current. If developers are working on 2.2, the documentarians need to
be as well. Right now I think each of the "documentarians" has a pet
project. What I hope is that in the future (or even now) that if
commiters need new functionality documented they will feel free to
ask us to do it. That is the role we play.
- once the wiki is "processed" (i.e. all documentation is (re)
moved), it
will only serve as a scratchpad, either for random thoughts/
proposals or
for users that want to offer documentation but have no editor
rights in
the Daisy site. I.e. the content of the wiki should be kept as
small as
possible and deprecated information should be removed as soon as
possible.
Same concerns as Leszek: writing docs in the wiki would really
make non-editors feel like second-class citizen. Additionally to
leaving comments, we may allow registered users with no particular
rights to edit documents belonging to a "scratchpad" collection,
distinct from the main document collection. That will allow us to
quickly move around good contributions to the main area and also
educate editor wannabees to the CMS features.
Here I have to disagree with you. I don't think that all the
content that is on the Wiki should necessarily find its way to
the :"formal" documentation. I think the wiki serves that purpose
well. It allows users a place to document things that they have
learned which may not have a good place in the formal
documentation. So, just because users can't directly update the
formal documentation I don't think they will feel like second class
citizens. I think they'd be quite surprised if they could update
the formal documentation. And actually, I think they would be
quite pleased and honored if whatever they wrote was moved from the
wiki into the formal docmentation by an editor.
I really don't see this as much different than how things are with
the code. Users can write patches and submit them to bugzilla or
they can post code snippets on the wiki, but they cannot update svn.
One of the things we'd like to get out of this is more user
participation. What I'd like to see is the Daisy site replace the
wiki for documentation purposes. I'd like guest to be able to browse
unfinished and incomplete documentation. I'd like anyone to be able
to write documentation and submit it for publication. The wiki still
has a place, but I've never seen as appropriate way to document things.
Glen Ezkovich
HardBop Consulting
glen at hard-bop.com
A Proverb for Paranoids:
"If they can get you asking the wrong questions, they don't have to
worry about answers."
- Thomas Pynchon Gravity's Rainbow
