trafodion-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dave Birdsall <dave.birds...@esgyn.com>
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
either.

Dave

-----Original Message-----
From: Gunnar Tapper [mailto:tapper.gunnar@gmail.com]
Sent: Wednesday, December 2, 2015 6:01 PM
To: dev@trafodion.incubator.apache.org
Subject: Proposal for documentation on website

Hi,

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
incubator.trafodion.apache.org/docs directory for the website.

The content of docs/target is checked into
https://git-wip-us.apache.org/repos/asf/incubator-trafodion-site.git via
manual checkout, copy, checkin and then svnpubsub, which does the actual
publication.

>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
docs/<version>
docs/<version>/<document>
docs/<version>/<document>/index.html (entry point to the web version of the
document)
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

docs/1.3.0/dcs_reference_guide/index.html
docs/1.3.0/dcs_reference_guide/_chapters
docs/1.3.0/dcs_reference_guide/dcs_reference_guide_1_3_0.pdf
docs/1.3.0/dcs_reference_guide/apidocs/index.html

Is this an OK organization? If so, I can write up instructions for how to
copy the different documents to their target
https://git-wip-us.apache.org/repos/asf/incubator-trafodion-site.git
directories.
In essence, the procedure would be:

1. Run the release build.
2. Checkout
https://git-wip-us.apache.org/repos/asf/incubator-trafodion-site.git
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
docs/<version>/client_installation_guide
.
.
.

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

Comments? Suggestions?

--
Thanks,

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

Mime
View raw message