[seam-dev] Documentation issues
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 <dmison(a)redhat.com>
To: Robb Greathouse <robb.greathouse(a)jboss.com>
CC: The Core <thecore(a)redhat.com>
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
Attachments:
- attachment.html (text/html — 3.5 KB)