Hi Wendy,
On 17-Jan-09, at 17:04 , Wendy Smoak wrote:
On Sat, Jan 17, 2009 at 10:36 AM, Christian Edward Gruber <[email protected]
> wrote:
I'm not so happy with the lack of integrated documentation. It
would be nice for more "how-to" to be right there available while
you're doing. But that's a minor thing.
Would including the existing docs at /documentation in the web-app
help, (are you trying to work while offline?) or are you looking for
something else?
Actually, that would be great, since then the application could
reference help into the /documentation space. It might be a bit
weird, since the docs are maven site generated, but site isn't run in
a standard build. Possibly the continuum-docs pom.xml could be
configured to execute site and then zip up the site in the packaging
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
that has no external access, merely access to an internal repository
of "approved" artifacts (banks are the prime examples of this). So
there's no way to get at the documentation, short of importing it
statically and hosting it on the internal network. I like the idea of
being able to pull up the docs at any time while I'm using the
software, so it's more self-contained.
However, when I wrote this I was thinking more of context-oriented
help - if not hover tool-tips, then creative use of white-space for
"what am I doing here" docs right in the forms. Explanations of
fields, etc.
My main concern is that it's hard enough to get the docs written and
kept updated with changes. If we also had docs integrated with the
pages (like hover help on the fields?) then I'd want to find a way
to reuse text from the apt docs or somehow make sure we're only
writing it once.
I agree - the problem is that with context-help, or help on fields,
it's really hard to put those snippets in the right places, but then
weave them together into an external doc. I agree the duplication is
a concern, but I've no great theories about fixing it. My own view is
that once it's in place, if a developer edits the form, they should
add or modify the appropriate hover text as a part of completing the
feature. I find maintaining that sort of documentation, once the
pattern is set, is way easier than external user docs, since if I
change a feature, the docs I need to change are right there with the
code/template.
Having said that, if someone can figure out a way to scrape the
template for a page and auto-generate documentation, then they would
garner my admiration, that's for certain.
cheers,
Christian
Christian E. Gruber - President / Senior Consultant
email: [email protected]
Isráfíl Consulting Services Corporation
mobile: +1 (289) 221-9839
"Keenness of understanding is due to keenness of vision..."
phone: +1 (905) 640-1119
