While I was looking at the Apache information pages, I noticed this
information about including documentation in a release:
There are also some compelling arguments for making the documentation for a
release available for browsing online. (Issuing documentation as compressed
archives is just another type of distribution and the standard rules for
artifacts apply.) This makes support of releases easier and helps users
understand which release is most appropriate for them.
Online documentation should be archived so that it can be easily recreated.
Though using www.apache.org/dist for these files is convenient and ensures
that they are archived, it should not be used for this purpose.
Documentation typically consists of many relatively small files and so is
inefficient to sync. Users will view it using http and so there is no
advantage in these files being distributed to the mirrors. The cost of
syncing to the mirrors should therefore be avoided.
The best approach is to commit the documentation for a release into
subversion. Then check out into a directory in the website. Generally,
checking generated documentation into source control is often considered bad
practise. But it is very suitable for fixing the documentation for a
particular release.
Roberta
-----Original Message-----
From: Carol Pearson [mailto:[email protected]]
Sent: Tuesday, November 17, 2015 10:30 PM
To: [email protected]
Subject: Re: Website Updates
Hi,
+1 on this last.
This makes sense to me, so long as it's aligned with the criteria for Apache
incubating projects. This makes it easier for folks to contribute
documentation changes that are versioned, and to change the website
framework, so win-win.. I definitely agree we need to keep versioned
documentation with the actual software and update that in conjunction with
checkins. That's separate from keeping older documentation versions
accessible, especially for current recommended versions versus
daily-build-ish updates. We can't expect everyone to jump to the latest
daily build, even if we keep the documentation more up to date.
-Carol P.
On Tue, Nov 17, 2015 at 5:44 PM, Gunnar Tapper <[email protected]>
wrote:
> So:
>
>
> - Web site in single branch of main repo
> - Generate documents from master, publish to release-specific landing
> pages
> - Generate web site, which pulls in the release-specific landing
> pages
>
> ?
>
> On Tue, Nov 17, 2015 at 6:31 PM, Venkat Muthuswamy <
> [email protected]> wrote:
>
> > I agree with Steve. The product documentation is tied to the source
> version
> > and should stay with the code repository.
> >
> > The artifacts from the product build can be staged some place before
> > the website is built.
> > We can probably script that part that pulls in the necessary
> documentation
> > files together.
> >
> > Venkat
> >
> > -----Original Message-----
> > From: Steve Varnau [mailto:[email protected]]
> > Sent: Tuesday, November 17, 2015 5:04 PM
> > To: [email protected]
> > Subject: RE: Website Updates
> >
> > Thanks, I thought that may be the case. It is location for
> > publishing to the staging and published sites.
> >
> > So the source ought to be in our main repo, but can be single branch
> > (either master or a branch just for web).
> >
> > If the maven build of the site needs docs from multiple releases,
> > then
> that
> > gluing together would have happen when prepping/generating the site,
> right?
> >
> > --Steve
> >
> >
> > > -----Original Message-----
> > > From: Gunnar Tapper [mailto:[email protected]]
> > > Sent: Tuesday, November 17, 2015 4:46 PM
> > > To: [email protected]
> > > Subject: Re: Website Updates
> > >
> > > That's a copy of the docs/target directory in the build. No source
> files.
> > >
> > > On Tue, Nov 17, 2015 at 5:44 PM, Steve Varnau
> > > <[email protected]>
> > > wrote:
> > >
> > > > Seems to me that product documentation should be versioned with
> > > > the product.
> > > >
> > > > Whereas there needs to be one web site that refers to multiple
> > > > versions of the product and docs.
> > > >
> > > > The project web site exists in incubator-trafodion-site repo,
> correct?
> > > > Or
> > > > is that just the staging location?
> > > > https://git-wip-us.apache.org/repos/asf/incubator-trafodion-site
> > > >
> > > > --Steve
> > > >
> > > >
> > > > > -----Original Message-----
> > > > > From: Gunnar Tapper [mailto:[email protected]]
> > > > > Sent: Tuesday, November 17, 2015 4:28 PM
> > > > > To: [email protected]
> > > > > Subject: Re: Website Updates
> > > > >
> > > > > Hi,
> > > > >
> > > > > My original suggestion was to separate out the web site and
> > > > > the documentation. Would that work given how; for example, the
> > > > > DCS asciidoc
> > > > is
> > > > > part of dcs/src/main/asciidoc?
> > > > >
> > > > > I believe that we can look at how other projects separate out
> > > > > these items for guidance. There will be a need to update the
> > > > > website for new release but that seems manageable in
> > > > > comparison to the current situation.
> > > > > Refer
> > > > to
> > > > > https://geode.incubator.apache.org/contribute/ for how that
> > > > > project handles documentation and the website.
> > > > >
> > > > > The question about artifacts seems to depend on the DCS
> > > > > documentation issue. You either move those files to the new
> > > > > source tree or you have to copy to a known place for the
> > > > > website to pick them up.
> > > > >
> > > > > Thanks,
> > > > >
> > > > > Gunnar
> > > > >
> > > > >
> > > > >
> > > > > On Tue, Nov 17, 2015 at 5:03 PM, Roberta Marton
> > > > > <[email protected]>
> > > > > wrote:
> > > > >
> > > > > > +1 - we do need to update the website and other artifacts
> > > > > > +separately
> > > > > > from
> > > > > > the main code and I would create a JIRA and file it under
> > > > > > build infrastructure.
> > > > > >
> > > > > > Some questions to ponder: . Have you given thought to how
> > > > > > the website changes will be separated from the Trafodion
> > > > > > product changes? Will there be a separate repository and
> > > > > > how will the repository be maintained?
> > > > > > Also,
> > > > > > will
> > > > > > the new repository only contain website changes? Will this
> > > > > > also be a good place to put documentation changes - as Hans
> > > > > > mentioned? When we
> > > > release
> > > > > > Apache artifacts, do we also have to release the
> > > > > > documentation (don't think so)?
> > > > > >
> > > > > > Roberta
> > > > > >
> > > > > > -----Original Message-----
> > > > > > From: Gunnar Tapper [mailto:[email protected]]
> > > > > > Sent: Tuesday, November 17, 2015 3:51 PM
> > > > > > To: [email protected]
> > > > > > Subject: Re: Website Updates
> > > > > >
> > > > > > Great. Should I create a jira to create a new docs branch?
> > > > > >
> > > > > > Thanks,
> > > > > >
> > > > > > Gunnar
> > > > > >
> > > > > > On Tue, Nov 17, 2015 at 4:48 PM, Hans Zeller
> > > > > > <[email protected]>
> > > > > > wrote:
> > > > > >
> > > > > > > +1
> > > > > > >
> > > > > > > Another thing I noticed with other sites, the Javadoc
> > > > > > > pages seem to
> > > > be
> > > > > > > available only for the latest release (at least that was
> > > > > > > my impression). It might be good to make those and other
> > > > > > > reference information like manuals available for older
> > > > > > > versions
> > as
> > > > > > > well.
> > > > > > >
> > > > > > > Another dimension is whether we put info on a static page vs.
> > > > > > > a wiki where people can edit and comment. Apache requires
> > > > > > > certain things to be on a page managed by source control,
> > > > > > > but IMHO it would be nice to have other info on a wiki,
> > > > > > > with discussions right near the page with the relevant
> > > > > > > content, so people can see and discuss common problems and
> > > > > > > their solutions. Also, the speed is much faster. Even if
> > > > > > > we put the non-wiki site in a separate repository, some
> > > > > > > rules for committing changes to it may still apply.
> > > > > > >
> > > > > > > Hans
> > > > > > >
> > > > > > > On Tue, Nov 17, 2015 at 3:33 PM, Christophe LeRouzo
> > > <[email protected]>
> > > > > > > wrote:
> > > > > > >
> > > > > > > > +1
> > > > > > > >
> > > > > > > > It can also enable different kind of contributions than
> > > > > > > > the ones on the code itself.
> > > > > > > >
> > > > > > > > Regards,
> > > > > > > > -clr
> > > > > > > >
> > > > > > > >
> > > > > > > > -----Original Message-----
> > > > > > > > From: Amanda Moran [mailto:[email protected]]
> > > > > > > > Sent: Tuesday, November 17, 2015 3:18 PM
> > > > > > > > To: dev <[email protected]>
> > > > > > > > Subject: Re: Website Updates
> > > > > > > >
> > > > > > > > +1
> > > > > > > >
> > > > > > > > Makes sense to me.
> > > > > > > >
> > > > > > > > Thanks Gunnar.
> > > > > > > >
> > > > > > > > On Tue, Nov 17, 2015 at 3:15 PM, Gunnar Tapper
> > > > > > > > <[email protected]>
> > > > > > > > wrote:
> > > > > > > >
> > > > > > > > > Hi,
> > > > > > > > >
> > > > > > > > > As it turns out, we immediately hit issues with having
> > > > > > > > > the
> > > > website
> > > > > > > > > as part of the product source tree.
> > > > > > > > >
> > > > > > > > > The website is really a standalone entity that
> > > > > > > > > operates at a different speed than the product and
> > > > > > > > > that should be on a
> > > > different
> > > > > > > > > release schedule than the overall product.
> > > > > > > > >
> > > > > > > > > The speed issue is that the review-then-commit model
> > > > > > > > > has long delays built in, which are counter productive
> > > > > > > > > for website development (since that development tends
> > > > > > > > > to be sporatic and
> > > > > > > > > clustered) thereby slowing down the updates and and
> > > > > > > > > forcing huge commits instead of incremental commits.
> > > > > > > > > The tie to a release is really odd since a website
> > > > > > > > > update is forcefully tied to a product release in such
> > > > > > > > > a model. A workaround would be to publish the content
> > > > > > > > > of the docs/target directory before the in-progress
> > > > > > > > > release is done, which doesn't really follow the
> > > > > > > > > spirit of
> > > > release
> > > > > > > > > versions. If anything, the website should have it's
> > > > > > > own
> > > > > > > > > version scheme.
> > > > > > > > >
> > > > > > > > > Given the precedence of other projects separating out
> > > > > > > > > the website and documentation, then it seems
> > > > > > > > > reasonable to do the same from Trafodion.
> > > > > > > > > I assume that the committers votes on this? Is a Jira
> > > > > > > > > needed or some other approach?
> > > > > > > > >
> > > > > > > > > Thanks,
> > > > > > > > >
> > > > > > > > > Gunnar
> > > > > > > > >
> > > > > > > > > On Tue, Nov 10, 2015 at 5:15 PM, Dave Birdsall
> > > > > > > > > <[email protected]>
> > > > > > > > > wrote:
> > > > > > > > >
> > > > > > > > > > Hi,
> > > > > > > > > >
> > > > > > > > > > Just thinking out loud.
> > > > > > > > > >
> > > > > > > > > > Pros to keeping just one repository:
> > > > > > > > > >
> > > > > > > > > > Makes it possible to update code and web site in one
> > > > > > > > > > pull request. I
> > > > > > > > > don't
> > > > > > > > > > know anyone who is doing that now however. Longer
> > > > > > > > > > term,
> > > though,
> > > > > > > > > > we will want to encourage documentation to be
> > > > > > > > > > updated alongside code so this may be
> > > > > > > > > the
> > > > > > > > > > direction we want to go.
> > > > > > > > > >
> > > > > > > > > > Makes it easier to have a notion of code + web site
> > > > > > > > > > being on
> > > > the
> > > > > > > > > > same release thread. Of course that can still be
> > > > > > > > > > done with separate repositories; it is just twice
> > > > > > > > > > the work from an infrastructure perspective.
> > > > > > > > > >
> > > > > > > > > > Pros for having separate repositories:
> > > > > > > > > >
> > > > > > > > > > Makes it easier for the web site to be "pan-release".
> > > > > > > > > > For example, one
> > > > > > > > > can
> > > > > > > > > > maintain separate pages for past releases and pages
> > > > > > > > > > for future
> > > > > > > > releases.
> > > > > > > > > >
> > > > > > > > > > It might be interesting to inquire of other projects
> > > > > > > > > > why they
> > > > do
> > > > > > > > > > things
> > > > > > > > > the
> > > > > > > > > > way they do.
> > > > > > > > > >
> > > > > > > > > > Dave
> > > > > > > > > >
> > > > > > > > > > -----Original Message-----
> > > > > > > > > > From: Gunnar Tapper [mailto:[email protected]]
> > > > > > > > > > Sent: Tuesday, November 10, 2015 3:59 PM
> > > > > > > > > > To: [email protected]
> > > > > > > > > > Subject: Website Updates
> > > > > > > > > >
> > > > > > > > > > Hi folks:
> > > > > > > > > >
> > > > > > > > > > I'm working on updating the website. As I look
> > > > > > > > > > around, I find that some projects seem to have a
> > > > > > > > > > separate repository for the website. I assume
> > > > > > > > > that
> > > > > > > > > > it's so that the website can be updated
> > > > > > > > > > asynchronously from the actual project.
> > > > > > > > > >
> > > > > > > > > > Examples:
> > > > > > > > > >
> > > > > > > > > >
> > > > > > > > > > - http://phoenix.apache.org/building_website.html
> > > > > > > > > > - https://geode.incubator.apache.org/contribute/
> > > > > > > > > >
> > > > > > > > > >
> > > > > > > > > > What would be the pros and cons you'd see for Apache
> > > > > > > > > > Trafodion?
> > > > > > > > > > Is anyone dead against a separate repository for the
> > > > > > > > > > website?
> > > > > > > > > >
> > > > > > > > > > --
> > > > > > > > > > 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,
> > > > > > > >
> > > > > > > > Amanda Moran
> > > > > > > >
> > > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > > --
> > > > > > 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.*
> > > >
> > >
> > >
> > >
> > > --
> > > Thank you,
> > >
> > > Gunnar Tapper
> > > Presales Manager
> > > Esgyn Corp.
> >
>
>
>
> --
> Thanks,
>
> Gunnar
> *If you think you can you can, if you think you can't you're right.*
>
