Mailing-List: contact dev-help@continuum.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@continuum.apache.org
Received-SPF: pass (nike.apache.org: local policy)
Message-Id: <5A1DC45C-3978-406D-A854-4825B4827E5D@israfil.net>
From: Christian Edward Gruber <cgruber@israfil.net>
To: dev@continuum.apache.org
In-Reply-To: <adba96190901171404j474121a8u756a74f723c28ed3@mail.gmail.com>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed; delsp=yes
Content-Transfer-Encoding: quoted-printable
Subject: Re: Integrated Documentation
Mime-Version: 1.0 (Apple Message framework v930.3)
Date: Sat, 17 Jan 2009 18:16:19 -0500
References: <adba96190901171404j474121a8u756a74f723c28ed3@mail.gmail.com>

Hi Wendy,

On 17-Jan-09, at 17:04 , Wendy Smoak wrote:
> On Sat, Jan 17, 2009 at 10:36 AM, Christian Edward Gruber =
<cgruber@israfil.net=20
> > wrote:
>> I'm not so happy with the lack of integrated documentation.  It =20
>> would be nice for more "how-to" to be right there available while =20
>> you're doing.  But that's a minor thing.
>
> Would including the existing docs at /documentation in the web-app =20
> help, (are you trying to work while offline?) or are you looking for =20=

> something else?

Actually, that would be great, since then the application could =20
reference help into the /documentation space.   It might be a bit =20
weird, since the docs are maven site generated, but site isn't run in =20=

a standard build.  Possibly the continuum-docs pom.xml could be =20
configured to execute site and then zip up the site in the packaging =20
phase, then un-compress them into the war.  Anyway, I like it.

The context is that in many situations my CI server is on a network =20
that has no external access, merely access to an internal repository =20
of "approved" artifacts (banks are the prime examples of this).  So =20
there's no way to get at the documentation, short of importing it =20
statically and hosting it on the internal network.  I like the idea of =20=

being able to pull up the docs at any time while I'm using the =20
software, so it's more self-contained.

However, when I wrote this I was thinking more of context-oriented =20
help - if not hover tool-tips, then creative use of white-space for =20
"what am I doing here" docs right in the forms. Explanations of =20
fields, etc.

> My main concern is that it's hard enough to get the docs written and =20=

> kept updated with changes.  If we also had docs integrated with the =20=

> pages (like hover help on the fields?) then I'd want to find a way =20
> to reuse text from the apt docs or somehow make sure we're only =20
> writing it once.

I agree - the problem is that with context-help, or help on fields, =20
it's really hard to put those snippets in the right places, but then =20
weave them together into an external doc.  I agree the duplication is =20=

a concern, but I've no great theories about fixing it.  My own view is =20=

that once it's in place, if a developer edits the form, they should =20
add or modify the appropriate hover text as a part of completing the =20
feature.  I find maintaining that sort of documentation, once the =20
pattern is set, is way easier than external user docs, since if I =20
change a feature, the docs I need to change are right there with the =20
code/template.

Having said that, if someone can figure out a way to scrape the =20
template for a page and auto-generate documentation, then they would =20
garner my admiration, that's for certain.

cheers,
Christian

Christian E. Gruber - President / Senior Consultant               =20
email:  cgruber@israfil.net
Isr=E1f=EDl Consulting Services Corporation                           =20=

mobile: +1 (289) 221-9839
"Keenness of understanding is due to keenness of vision..."       =20
phone:  +1 (905) 640-1119