continuum-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Brett Porter <br...@apache.org>
Subject Re: Integrated Documentation
Date Mon, 19 Jan 2009 07:50:29 GMT

On 17/01/2009, at 5:50 PM, Wendy Smoak wrote:

> On Sat, Jan 17, 2009 at 4:16 PM, Christian Edward Gruber
> <cgruber@israfil.net> wrote:
>
>> The context is that in many situations my CI server is on a network  
>> that has
>> no external access,
>
> Or we could at least offer a separate zip download of the docs, to
> make it easier for those who need to access them offline.

Archiva does both at the moment - you may like to life it's  
configuration for a future Continuum release.

>
>
>> 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.
>
> I agree we need more of this; on things like installations and
> notifications it's not at all clear what things mean... unfortunately
> I'm not good enough with page design to figure out how to make it
> useful and unobtrusive.

I agree as well, though a simple link to the documentation (if  
bundled) would be a good start (just a help link on each page).

As for linking snippets to docs - well, you can have the docs extract  
them using the snippet macro if they are marked in the pages  
appropriately (they are possibly even in resource files, so you can  
access them properties and share them via a separate module that  
contains the bundles).

However I think I'd like to see repeated duplication that makes the  
effort worthwhile - I think the snippets tend to be reworded to suit  
the condensed/contextual nature where the docs are going to give a  
lengthier explanation. If they context help is there and sufficient,  
the doc page is probably not needed if it's just aggregating that.

Christian, would you be interested in submitting patches for some  
contextual help?

Cheers,
Brett

>
>
> -- 
> Wendy

--
Brett Porter
brett@apache.org
http://blogs.exist.com/bporter/


Mime
View raw message