cxf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Johnson, Eric" <Eric.John...@iona.com>
Subject Wiki Spaces (was RE: Wiki and Web)
Date Mon, 18 Sep 2006 18:31:35 GMT
That sounds like a good idea. Dan K. actually pointed out to me that it
is possible to have multiple spaces and use each one for slightly
different purposes. For example, Geronimo has one for their website, one
for a knowledge base, one for documentation, one for developers, one for
project management, a sandbox, and two others.
I think that may be a bit of overkill, but I do like the idea of having
more than one space for the project. How about we use four spaces:
1. Web site space that we use to create the front page. This space will
only be editable by developers on the commit list. Used for editing the
site and then exported to static HTML.
2. Developer space for putting up development plans, architectural docs,
etc. Also open to the developers on the commit list, plus active
contributors to the code base.
3. Documentation space for user facing docs. Same as above, but also
open to some users.
4. General purpose wiki. Open to the general public and never gets
exported to a static state.
This will give us the benefits you laid out for using confluence and
provide a little bit of control over who can edit what. It will also
mean we can have slightly different presentation templates for different
parts of the site should the need arise.

> -----Original Message-----
> From: Dan Diephouse [mailto:dan@envoisolutions.com]
> Sent: Friday, September 15, 2006 12:03 PM
> To: cxf-dev@incubator.apache.org
> Subject: Re: Wiki and Web
> 
> How about we get the wiki structured up a bit and then we can switch
> later if we need to? Maybe try it for M1 and then switch if we need to
> for M2? Or if its clear it isn't working before M1 we can reevaluate
> then too.
> 
> - Dan
> 
> Johnson, Eric wrote:
> 
> >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:debbiemoynihan@gmail.com]
> >>Sent: Friday, September 15, 2006 10:31 AM
> >>To: cxf-dev@incubator.apache.org
> >>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 <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
> >>>>
> >>>>
> >>>
> >>>
> >
> >
> >
> 
> 
> --
> Dan Diephouse
> (616) 971-2053
> Envoi Solutions LLC
> http://netzooid.com



Mime
View raw message