trafodion-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gunnar Tapper <tapper.gun...@gmail.com>
Subject Re: Proposal for documentation on website
Date Fri, 04 Dec 2015 03:32:27 GMT
Hi,

Would it be possible to come up with an official repository to host
Trafodion sources for things like manual images, presentations, etc.? For
example, we store the images used in manuals with the manual but there's no
place to store the image source, which might be a powerpoint file or
something else. We're also creating presentations for advocacy.

Or, do we simply upload these type of objects to a wiki page?

Thanks,

Gunnar

On Thu, Dec 3, 2015 at 4:42 PM, Steve Varnau <steve.varnau@esgyn.com> wrote:

> In my opinion, we don't want files in those formats in our source repo.
> Even
> if they are deleted later, they live in history forever and have to be
> downloaded with every clone.
>
> If you want to version them somewhere else until they are in a suitable
> format, you can always create a repo on github. I'm sure other temp
> solutions are around too.
>
> --Steve
>
>
> > -----Original Message-----
> > From: Gunnar Tapper [mailto:tapper.gunnar@gmail.com]
> > Sent: Thursday, December 3, 2015 2:14 PM
> > To: dev@trafodion.incubator.apache.org
> > Subject: RE: Proposal for documentation on website
> >
> > They are in shape to be in 1.3 but the source is in Word. Is there an
> > alternative repository for .doc, .ppt, etc files? We do want such
> > documents
> > to be protected and under change control, right? The same question
> applies
> > to source for images used in asciidoc documents...
> > On Dec 3, 2015 2:16 PM, "Steve Varnau" <steve.varnau@esgyn.com> wrote:
> >
> > > Okay, then it sounds like the docs can be generated to PDF to post on
> > > the
> > > project site, but are not in shape to include in the 1.3 code release
> at
> > > all.
> > >
> > > --Steve
> > >
> > >
> > > > -----Original Message-----
> > > > From: Gunnar Tapper [mailto:tapper.gunnar@gmail.com]
> > > > Sent: Thursday, December 3, 2015 12:02 PM
> > > > To: dev@trafodion.incubator.apache.org
> > > > Subject: Re: Proposal for documentation on website
> > > >
> > > > No, it's not. The source is in Word format, which has been updated
> > > > with
> > > > Apache Licenses.
> > > >
> > > > On Thu, Dec 3, 2015 at 12:18 PM, Roberta Marton
> > > > <roberta.marton@esgyn.com>
> > > > wrote:
> > > >
> > > > > Is the documentation in xml format actually good?  I was unable to
> > > > > access
> > > > > the information - but it could be operator error.
> > > > >
> > > > >     Roberta
> > > > >
> > > > > -----Original Message-----
> > > > > From: Steve Varnau [mailto:steve.varnau@esgyn.com]
> > > > > Sent: Thursday, December 3, 2015 11:10 AM
> > > > > To: dev@trafodion.incubator.apache.org
> > > > > Subject: RE: Proposal for documentation on website
> > > > >
> > > > > The PDF's are generated. I don't think we should be putting
> > > > > generated
> > > > > files
> > > > > in the source. The XML files there now are the sources, even if
> they
> > > are
> > > > > not
> > > > > yet in the preferred format, so why not include them?
> > > > >
> > > > > --Steve
> > > > >
> > > > >
> > > > > > -----Original Message-----
> > > > > > From: Roberta Marton [mailto:roberta.marton@esgyn.com]
> > > > > > Sent: Thursday, December 3, 2015 10:30 AM
> > > > > > To: dev@trafodion.incubator.apache.org
> > > > > > Subject: RE: Proposal for documentation on website
> > > > > >
> > > > > > I was planning on copying the pdf and word documents that Gunnar
> > > > > > produced
> > > > > > to:
> > > > > >
> > > > > > /docs/src/resource/docs and include them in the source tar.
> > > > > >
> > > > > > I was not planning on including the existing documents in the
> > > > > > source
> > > > > > tar, e.g. docs/client_install
> > > > > >
> > > > > > Should  I do something else?
> > > > > >
> > > > > >     Roberta
> > > > > >
> > > > > > -----Original Message-----
> > > > > > From: Steve Varnau [mailto:steve.varnau@esgyn.com]
> > > > > > Sent: Thursday, December 3, 2015 10:25 AM
> > > > > > To: dev@trafodion.incubator.apache.org
> > > > > > Subject: RE: Proposal for documentation on website
> > > > > >
> > > > > > Gunnar,
> > > > > >
> > > > > > Yes, it is okay by me for generated PDF to be in the site repo,
> > > > > > but
> > > > > > I'd prefer not to have that format checked into the source repo.
> > > It'll
> > > > > > be great once we have the asciidoc versions there.  I know --
one
> > > step
> > > > > > at a time!
> > > > > >
> > > > > > --Steve
> > > > > >
> > > > > >
> > > > > > > -----Original Message-----
> > > > > > > From: Gunnar Tapper [mailto:tapper.gunnar@gmail.com]
> > > > > > > Sent: Thursday, December 3, 2015 9:52 AM
> > > > > > > To: dev@trafodion.incubator.apache.org
> > > > > > > Subject: Re: Proposal for documentation on website
> > > > > > >
> > > > > > > Hi Steve,
> > > > > > >
> > > > > > > We have those documents in Word/PDF format at the momement
plus
> > > > the
> > > > > > > maybe-yet-to-be-completed XML-to-asciidoc format. For now,
I
> > > propose
> > > > > > > that we provide PDF access and then complete the migration
to
> > > > > > > asciidoc later.
> > > > > > > OK?
> > > > > > >
> > > > > > > Thanks,
> > > > > > >
> > > > > > > Gunnar
> > > > > > >
> > > > > > > On Thu, Dec 3, 2015 at 10:35 AM, Steve Varnau
> > > > > > > <steve.varnau@esgyn.com>
> > > > > > > wrote:
> > > > > > >
> > > > > > > > Gunnar,
> > > > > > > >
> > > > > > > > For the last four, you list as word/pdf, but the source
xml
> > > > > > > > files
> > > > > > > > for them is in the docs tree in the incubator-trafodion
repo.
> > > > > > > > I
> > > > > > > > believe you are right, the goal was to convert them
from xml
> > > > > > > > to
> > > > > > > > asciidoc.
> > > > > > > >
> > > > > > > > --Steve
> > > > > > > >
> > > > > > > >
> > > > > > > > > -----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
> > > > > > > > > .g
> > > > > > > > > it
> > > > > > > > > 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
> > > > > > > > > .g
> > > > > > > > > it
> > > > > > > > > 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
> > > > > > > > > .g it 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.*
> > > > > > > >
> > > > > > >
> > > > > > >
> > > > > > >
> > > > > > > --
> > > > > > > Thanks,
> > > > > > >
> > > > > > > Gunnar
> > > > > > > *If you think you can you can, if you think you can't you're
> > > right.*
> > > > >
> > > >
> > > >
> > > >
> > > > --
> > > > Thanks,
> > > >
> > > > Gunnar
> > > > *If you think you can you can, if you think you can't you're right.*
> > >
>



-- 
Thanks,

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

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message