Debbie,
+1 for prettying up the wiki. The addition of a navigation bar would
really help make it easier to find content and add a sense of structure
to it. If you want to work on this it would be great.
As for how to do the documentation, I'm still thinking. Dan D. has made
a good case for using the wiki, but I still have concerns. Largely, I
think those concerns are more philosophical than practical, but I need
to chew on it a bit more.
Cheers,
Eric
-----Original Message-----
From: Debbie Moynihan [mailto:[EMAIL PROTECTED]
Sent: Friday, September 15, 2006 10:31 AM
To: [email protected]
Subject: Re: Wiki and Web
I think that both the dynamic wiki based docs and the release level
docs
both have significant value. I do think that the expectation of an
open
source project is not the same as traditional commercial software so
just
wiki based documentation would be acceptable. That said, release
level
documentation would be really beneficial for users and a nice to have.
I
have a lot of experience with customizing templates for communities
and
web-sites and writing copy/documentation (although I am new to
Confluence
but it seems pretty easy). I'd like to volunteer to expand the wiki
format
using Confluence themes (left navigation theme) and best practices
from
apache projects and other confluence based projects listed previously
in
the
thread. Eric would it make sense to hold off and see how the
documentation
progresses for a bit and then determine if we also want to create
separate
formal release level documentation - or if you want to get going on
the
docbook documentation right away you can focus on that and you won't
have
to
learn as much about Confluence. I've done some research on Confluence
themes
etc and it seems pretty straightforward, although I will need wiki
admin
privileges (preferred) or I can provide instructions to someone with
admin
privileges. My user name is DebbieMoynihan on Confluence.
Whatever we decide on the documentation, I think it makes sense to use
the
left nav bar theme so we can see all of the critical links to the left
instead of having to scroll to the bottom of the page.
Debbie
On 9/12/06, Johnson, Eric <[EMAIL PROTECTED]> wrote:
Oisin,
Your points are well stated as always. I think they hit a lot of the
contentions spot on.
As I writer, I find that wikis are limited for the type of work I
want
to do. I want to create formal documentation that supports a stable
release. This documentation is targeted at users who are developing
production systems and are not likely to jump to the next hot
release.
This type of documentation is not really benefited by agility, is
highly
organized, has a consistent level of quality, is thoroughly
reviewed,
and follows some pretty tight style guidelines. It has indexes and
other
aids to finding information in it.
However, for developers who want to get documentation about how
their
code works or how it is designed a wiki is more than enough. Wikis
provide a quick and easy way of creating content and keeping it
updated.
For cutting edge, fluid material they are great. Experience has
shown me
that having a wiki available to the engineers does encourage the
flow of
information from the developers to the writers.
I like your idea of a blended approach where developers create
content
about their features, and users can add stuff also, using the wiki.
This
stuff can be easily published and made easily accessible. In
addition,
we can filter that information into formal documentation that is
more
tightly controlled for quality, style, tone, message, etc.. The more
formal documentation can also be accessed on through the web site
and be
released as a separate package if that makes sense.
I know this seems like a "corporate" way of thinking, but there must
be
a good reason that there is a whole industry out there for creating
formal documentation for popular open source projects.
Cheers,
Eric
-----Original Message-----
From: Hurley, Oisin
Sent: Monday, September 11, 2006 6:57 AM
To: [email protected]
Subject: Re: Wiki and Web
Lots of interesting points here on the documentation aspect of the
project, and I'm enjoying the thread :) Of course I can't resist
adding my 2c, in bullet point form.
* having worked as a developer for a number of years, I have
regularly seen releases 'released via press release' and then
the documentation follow the code within a 30 day ship window
* having used OSS for a number of years, I have regularly seen
documentation updated at a very fine-grained level and in a
timely fashion when bugfixes happen...also I have seen
documentation
that never actually appears :)
* I disagree that wikis are unprofessional, I think that they
are very acceptable - if it's good enough for IBM, BEA, Oracle,
SAP and co. (http://www.osoa.org/display/Main/Home) then I think
is has made it's professional debut. However, some wikis can
look awful *cough*moinmoin*cough* :)
* I, personally, find it easier to write for wiki than docbook,
purely because I level of tooling required for wiki is less than
that required for docbook given a set level of productivity.
However, if I was writing full-time or mostly full-time, then I
wouldn't use the wiki, I would use docbook.
* I, personally, find wikis very frustrating because I can't
update them offline without copying and pasting. Some day I
will need to fix this.
* I, personally, think that using a wiki strengthens the
developers
connection to the document and increases their resolve to actually
update the thing in the first place. Remember that one of the
big challenges a tech writer has is actually getting information
out of the developers - blood/stone and all that (generalization
alert :)
* I, personally, think that a developer is not anywhere as
likely
to be able to write as well as a tech writer, so I think
that it is a positive thing for those skilled in the exposition of
technical <language-of-choice> to filter/review the documentation.
Of course, after making all those points the only conclusion that
I can come to is that we might need to end up with a blended
approach,
so that during the development cycle developers can update a wiki,
so that snapshots are up-to-date documented, and then coming up
to a release perhaps the documentation developers can engage to
move, prune, clean and otherwise sanitize the wiki content and
transfer it to a docbook format for a doc release synched with
the software release. That way everyone gets to use their own
fave tools, the code devs can make fine-grained immediate
changes to pieces of wiki and doc devs can have a fairly reliable
corpus upon which to base release doc.
Thoughts?
--oh
