trafodion-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dave Birdsall <>
Subject RE: Proposal for documentation on website
Date Thu, 03 Dec 2015 16:36:19 GMT
Hi Gunnar,

I think your proposal is excellent.

I think the greater concern is getting the documentation up-to-date. Just as
one example, I was using the Client Installation Guide last week to install
JDBCT4 and Trafci on my Windows 8 laptop. The instructions in the guide seem
to fit Windows 7 pretty well but need updating for Windows 8. Also, the
instructions seem to fit Java 1.7 pretty well, but the organization of JRE
and JDK seem to have changed in Java 1.8, which is what you get if you go to
the Java download page today.

As far as I know, none of the other manuals have been updated recently


-----Original Message-----
From: Gunnar Tapper []
Sent: Wednesday, December 2, 2015 6:01 PM
Subject: Proposal for documentation on website


The Trafodion documentation is a bit challenging to deal with at the moment.
At the moment, I know of the following manuals/guides:

   - DCS Reference Guide (asciidoc) -- dcs/src/main/asciidoc
   - DCS API Docs (Javadoc)
   - REST Server Reference Guide (asciidoc) -- core/rest/src/main/asciidoc
   - REST API Docs (Javadoc)
   - Client Installation Guide (Word/PDF) -- docs/resources/docs
   - Command Interface Guide (Word/PDF) -- docs/resources/docs
   - odb User Guide (Word/PDF) -- docs/resources/docs
   - SQL Reference Guide (Word/PDF) -- docs/resources/docs

The documentation should be part of a release's source tree and, therefore,
be versioned. Further, the documentation should be available on the website.

The website is rendered into docs/target. The documents go into
docs/target/docs, which means that there will be an directory for the website.

The content of docs/target is checked into via
manual checkout, copy, checkin and then svnpubsub, which does the actual

>From what I understand, the goal is to convert all documentation into
asciidoc providing both web and PDF version of each document. As such, I'd
believe that the web site's docs directory should be organized per version;
that is, docs/<version>. If I am correct, then I think that the preferred
layout would be:

docs/<version>/<document>/index.html (entry point to the web version of the
docs/<version>/<document>/_chapters (web version of the document; that is,
the content) docs/<version>/<document/<document>.pdf (PDF version of the
document docs/<version>/document/apidocs/index.html (entry point to the web
version of the API docs, if they exist)

Using DCS as an example, we'd have


Is this an OK organization? If so, I can write up instructions for how to
copy the different documents to their target
In essence, the procedure would be:

1. Run the release build.
2. Checkout
3. Create the new docs/<version> directory.
4. Create dcs_reference_guide directory
5. Copy all files from dcs/target/site to docs/<version>/dcs_reference_guide
n. Move docs/target/docs/Trafodion_Client_Installation_Guide.* to

Admittedly, this is both manual and clumsy but I think it organizes the
information in a manner that allows for future automation.

Comments? Suggestions?


*If you think you can you can, if you think you can't you're right.*

View raw message