On Wed, 2010-11-03 at 16:31 -0400, Robb Greathouse wrote: 
> Hi,
> 
> In the field we come across client complaints about documentation and what we could do to make it suck less.  Where should we funnel these?  It would be great if there was a place (Version control) where we could enter clarifications into the document.  They wouldn't go out right away, but they could accumulate there where someone could look at them and accept or reject them for regular updates to documentation.
> 
> For example, here is one I hear all the time.  We have snippets from xml files showing how to configure something.  An experienced developer will recognize which XML file it belongs in right away.  However, a new comer or someone who configures infrequently may not be able to figure out which xml file the snippet pertains.
> 
> Suggestion.  Put the FQN for the file in the title to the snippet.  
> 
> Example:  jboss/servers/[server]/conf/standardjboss.xml
> 
>           OR
> 
>           [Application].ear/WEB-INF/web.xml
> 
> Now that there are so many jboss-service.xml files the confusion is growing.
> 
> Robb Greathouse
> JBoss
> CELL   (505) 750-3481
> skype: rgreathouse
> 

Log a bug against the document :-)

If it is a product document (JBoss Enterprise Widget Platform) then
there should be a feedback section right at the beginning with the info
about where/how to log docs bugs.  It's not very discoverable IMHO but
it is there.

If it is a community document then your milage may vary but each project
generally has a  docs component in JIRA.

In that particular example it's probably better to have the example
title summarize the purpose of the example, rather than a file name.
The accompanying procedure that the example is illustrating should
define what file/s etc it applies to.


---
Darrin Mison
Red Hat JBoss Middleware Documentation