db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Jean T. Anderson" <...@bristowhill.com>
Subject Re: Holistic getting started approach
Date Fri, 03 Feb 2006 01:05:49 GMT
David W. Van Couvering wrote:
> Hm.  You mention that *anybody* can update the Wiki.  Perhaps that's not 
> such a bad thing.  Postgres and PHP both have user-updatable 
> documentation, and this has become very valuable.

I need to clarify that I didn't mean to include the Derby docs in my 
discussion below, only the main web site pages.

Is that what you're referring to for Postgres and PHP? do they support 
update of web site content separate from the product docs? I thought PHP 
had support for commenting on the product docs, but that isn't what I'm 
talking about here.

Product doc updates could also be considered, but would entail feedback 
to the DITA source for the Derby docs.

> What if we had a controlled "official" version of the docs, and a 
> Wikified version of the docs that can be updated/appended to by anybody?

I would actually prefer a simpler approach. If a page should be 
updateable by anyone, then move it to the Wiki.  :-)

An example of something that cannot be moved is the downloads page at 
http://db.apache.org/derby/derby_downloads.html and all it's associated 
release pages.


> Here's a thought as to how to do that:
> - Use Forrest's great MVC approach to generate a Wiki-friendly version 
> of the docs and publish this to the Wiki
> - Allow users to annotate the docs on the Wiki site
> - At next release, merge valuable user comments into the docs, and then 
> generate a new Wiki-friendly set for that version
> The only downside is comments that we don't consider "valuable" would 
> get orphaned in prior version doc sets on the Wiki set.  But maybe 
> that's OK...
> Thoughts?
> David
> Jean T. Anderson wrote:
>> Daniel John Debrunner wrote:
>>> Looking at Stan's WMD, sorry WWD document in DERBY-913 I want to promote
>>>  a holistic approach to making getting started on Derby easier. Thus by
>>> improving various areas such as documentation, web-site, product,
>>> tutorials, FAQ etc. together we can gain a bigger benefit than by
>>> increasing individual items to make up for deficiencies in other areas.
>> The web site needs a huge overhaul. Here are some of the issues I've 
>> been mulling over.
>> (1) Web site content isn't trivial to update
>> Whether the web site is in Forrest, Maven, or Anakia (those seem to be 
>> the big three at Apache), it involves learning the file formats those 
>> products support and the build process, and this learning curve is a 
>> barrier.
>> We've had a much higher rate of contribution to the Derby Wiki.
>> I'd like to move as much of the highly changing information on the web 
>> site to the Wiki as we can. For example, I think that all of 
>> http://db.apache.org/derby/integrate/misc.html can be moved to the 
>> Wiki -- and reorganized. Some is eclipsed by 
>> http://wiki.apache.org/db-derby/UsesOfDerby anyhow, but there are 
>> categories not handled by that Wiki page.
>> We'll have to strike some sort of balance, though. One issue with the 
>> Wiki is *anyone* can update it. Anything that requires controlled 
>> updates by committers must stay on the web site.
>> (2) New users can't easily find what they need
>> Too many responses to posts on derby-user consist of an URL to that 
>> information on the web site (or, lately, even on the Wiki).
>> The good news is we have a lot more content than we did a year and 
>> half ago. The bad news is I've pretty much just shovelled it in and 
>> some of it's pretty tangled now.
>> Perhaps a master "Start Here" page would help that is specifically 
>> tailored for new users. It could be on the web site or the Wiki, with 
>> a prominent tab on the web site that goes directly to that page.
>> (3) It's hard to find the downloads
>> I'm surprised by the number of requests I get which are "where are the 
>> downloads?" Even though downloads are on the home tab, they clearly 
>> aren't visible. So make downloads its own tab?
>> The real estate of a web browser can accommodate only so many tabs, so 
>> we have to choose carefully. I'm hoping to free up some time soon to 
>> look more closely at each of these areas.
>>  -jean

View raw message