I thought this might be relevant to us. It would be great if each of
the module's docs had a link in the introduction to the module's JIRA
for readers to submit documentation-related issues.
-------- Original Message --------
Subject: Re: On sucking less
Date: Thu, 04 Nov 2010 12:05:18 +1000
From: Darrin Mison <[email protected]>
To: Robb Greathouse <[email protected]>
CC: The Core <[email protected]>
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
_______________________________________________
seam-dev mailing list
[email protected]
https://lists.jboss.org/mailman/listinfo/seam-dev
