On 9/10/06, Dan Diephouse <[EMAIL PROTECTED]> wrote:
Johnson, Eric wrote:
>> First, I don't actually believe that this is how
>> documentation is created. Often a release is pushed out and then
>> documentation is written. Documentation has a life of its own beyond
>> just the initial release.
>>
>
> Having worked as a doc writer for a number of years, I have never seen a
> release pushed out with out documentation. The documentation often does
> get improved after the initial release, but it is solid before hand. My
> experience is entirely based on working for a company that wants to sell
> software, not an open source project however.
>
>
My experience is that in OSS, while some areas may be solid, a lot of it
will probably suck due to the rapid nature of change. Most docs will
continue to be improved past the initial release.
>> Second, I am of the philosophy that documentation should be part of
>>
> the
>
>> continuous improvement cycle of the project and it is impossible to
>> separate out from developing and support of users. For instance, with
>>
> I
>
>> read the xfire user's list and a question comes up that isn't
>>
> addressed
>
>> in the docs, I go and write something, then point users to it. Or I
>> write a response and ask users to add to the docs. (a lot of times
>>
> they
>
>> even do a really thorough job).
>>
>> I think the wikipedia provides a great example. It goes through
>> continuous improvement and people watch it religiously for any
>> backtracks. This makes documentation much more agile and makes it much
>> more open/approach to others.
>>
>
> I too think that documentation is an ongoing process and as people come
> up with new issues, use cases, and other suggestions for improvement the
> documentation should be updated. I also like the idea that any user can
> add information about the product. However, I also think that you need
> to have both a place where user supplied information can live and a
> separate place where documentation that has been reviewed, vetted, and
> given an official stamp of approval lives. Most teachers I know would
> not accept Wikipedia as a valid reference for information simply because
> it does not have a strict review process. I'm going to go out on a limb
> and guess that most major companies, who we hope are going to use
> CeltiXfire, are not going to accept documentation that is on a wiki as
> sufficient.
>
>
I think you're throwing a lot FUD at wikis here that is undeserved. We
aren't trying to convince a teacher here, we're trying to to create the
best overall documentation for the projects user. While there may not be
quite the delay before publishing, I think the wikipedia makes up for
that in its agility and extensiveness. I don't think that you can say
that the documentation won't be reviewed either. People will be watching
the documentation. There are many projects out there that use wikis and
they can work very well. I don't think anyone is going to object simply
because its a wiki. Do people not use OpenSymphony projects
(http://www.opensymphony.com/) because they are backed by a wiki? Or
ActiveMQ (http://activemq.org/site/home.html)? Or dozens of others?
>>> The same would go for versioned, official documentation. The source
>>> should be stored in the project trunk with the code and built as part
>>>
> of
>
>>> the project. When a version of the product is released, the vetted
>>>
> and
>
>>> reviewed documentation can be packaged and delivered as part of the
>>> download. It can then also be pushed out to the Web site.
>>>
>>>
>>>
>> I disagree that documentation should be so strictly version with the
>> project as it often continues to improve outside of the release cycle.
>> Docs are never done.
>>
>>
> How do you keep the documentation aligned with releases? What if an
> outside entity, such as IONA, wants to consume and repackage the
> documentation for a particular release?
>
Documentation can be aligned by creating a new wiki space with each
major version and copying the old docs over. For consumers - you could
export the docs as XML/HTML/etc. You could even write an xslt
transformation to turn the confluence xml export into docbook. If IONA
feels that people want a cleaned up/docbook'd version of the wiki they
could always provide that as a value add.
> All in all I agree that a wiki is a great way to encourage community
> contribution and provides a fast way to get content produced. However,
> they also present problems such as versioning, image, structure,
> indexing, navigability... Once you get beyond a few bits of
> documentation, a Wiki can get cumbersome to navigate. They also, in my
> opinion, lack a certain amount of credibility and professionalism. The
> Apache Web server and Tomcat don't use wikis for their docs and I doubt
> their users would be pleased if they decided to switch to a wiki.
>
>
Let me address your concerns:
Image: Create a good template for confluence. OpenSymphony has a decent one.
Structure: Confluence is a hierarchical wiki, allowing you to create
structure.
Indexing: Just create a Navigation page for the lefthand navigation and
an index page for the user's guide.
Navigability: See above.
Professionalism: I disagree that a wiki is unprofessional. If you have a
good template, it doesn't need to look like a wiki. The OpenSymphony
site looks better than a lot of apache sites to me. Take Tomcat for
example: Tomcat has the most horribly ugly documentation.
I think Stripes is one of the best examples of good documentation via
Confluence:
http://stripes.mc4j.org
Then again, Spring's documentation looks excellent using DocBook:
http://static.springframework.org/spring/docs/2.0.x/reference/index.html
I'll be interested to see which route you go. It's an interesting
idea to author in Confluence and export to DocBook.
Matt
Cheers,
- Dan
--
Dan Diephouse
Envoi Solutions
http://envoisolutions.com
http://netzooid.com/blog
