Mailing-List: contact derby-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: <derby-dev@db.apache.org>
Received-SPF: pass (asf.osuosl.org: domain of scotsmatrix@gmail.com designates
 66.249.92.175 as permitted sender)
DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws;
        s=beta; d=gmail.com;
        h=received:message-id:date:from:to:subject:mime-version:content-type:content-transfer-encoding:content-disposition;
        b=bjRcNc76sKPFHRu68HLE2pzZPIOzpHv8/b0zNDpHH2taaaRAWyX+/UInsSku9mH+0Re4gWZzhjCKYpj/Mj7YCPY42nJ2xc0eZ3rKuI1fcgllB5ikCDwNRhsBfFBY0F+Orr34gOIyNvHe6zXGPlzeeHVKlyR0y42GJwFslaxdysQ=
Message-ID: <9f40b500610100922p31d3a595n73f459cd59b6404@mail.gmail.com>
Date: Tue, 10 Oct 2006 09:22:29 -0700
From: "Laura Stewart" <scotsmatrix@gmail.com>
To: derby <derby-dev@db.apache.org>
Subject: Discussion: What prevents you from updating derby documentation?
MIME-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

The Derby Documentation page that describes how to setup your
environment, update the files, and submit patches.
http://db.apache.org/derby/manuals/dita.html

Yet there are very few contributors who actually update the documentation.  WHY?
What prevents you from updating the documentation when you update the code?

Please add your suggestions for the things that you would like to see
updated/added to make it easier to for people to update the Derby
documentation.

Here are a few of my recommendations:

1) The instructions on the Derby Documentation page need to be more
comprehensive... there are missing steps or assumptions made about a
contributors knowledge.
1.a. The instructions for downloading and unzipping the DITA toolkit
are for the first time that you do it.  If you already have it
downloaded and unzipped, the steps are missing for what you should do.

2) For new information, there aren't any "templates" for the topic
types: concepts, reference, task.  There also isn't a good description
of how to decide which type to use.

3) There are no guidelines for how to tag the text.


-- 
Laura Stewart