cxf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Debbie Moynihan" <debbiemoyni...@gmail.com>
Subject Re: Wiki and Web
Date Fri, 15 Sep 2006 14:30:49 GMT
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 <Eric.Johnson@iona.com> 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: cxf-dev@incubator.apache.org
> > 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
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message