continuum-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christian Edward Gruber <cgru...@israfil.net>
Subject Re: Integrated Documentation
Date Sat, 17 Jan 2009 23:16:19 GMT
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 
> > 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:  cgruber@israfil.net
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






Mime
View raw message