Hi Chris,
Some comments inline below.
On 8/28/12 8:52 AM, Christopher Brooks wrote:
Hi Michelle,
Greg and Chris, I'd like to propose we reconsider the way the release
documents are structured. Do we really need to create a complete set
of installation and configuration guides for each release? Why not
I'm ok with considering a change. The way it is now makes it very easy
for the release manager, just clone the docs and done. But the links
are a pain.
We use 1.2 locally, it's nice to just be able to look up the 1.2 docs
and go from those. But I'm not sure how this scenario would play out
if the only docs available are the "current release" docs; would we
have to read back through the 1.4 and 1.3 release notes to understand
what 1.2 instructions were?
Also, when we create the updated release docs, don't we have to clone
trunk and fix links anyways? The way it works now is that as people
add new features to trunk, they update the trunk docs, then we verify
during the release process. I wouldn't like to see them updating the
"current release" docs with instructions only suitable for trunk,
especially since those instructions wouldn't have gone through QA.
The real problem to me is that confluence sucks at cloning trees. The
insanity that the page title has to be unique is an unfortunate design
decision on their part. Is there a better tool for our job of release
notes?
OK, I guess I didn't realize the need to have separate 1.2 install and
configure docs. With that in mind, and looking at the problem of cloning
trees, here's an entirely different alternative I've seen other projects
using Confluence do it this way, but not sure if it's really a good or
bad approach. The idea is that each set of release docs is it's own wiki
space. Then the page titles and links don't need to change. You can
clone an entire space very easily, then just update it. So install and
configure trunk would be it's own space that you just clone with each
release.
This, though, isolates instructions for installing and configuring as
separate spaces from the developer wiki and (proposed) adopter wiki. I'm
not sure if this addresses the goal of providing adopters with better
documentation.
(We could switch straight to a text format or even just a set of html
pages in the source tree. But we want this to be online too, and I
like having the docs "centralized" at the opencast site so we can
address errata on the fly.)
Regarding the concern about opening up access. We could still
restrict editing of these pages to a limited group of people. We
could also relay on "watching" pages to monitor for changes, thereby
Why does MHDOC ever have to change? It's essentially the released
version of the docs. Except for minor updates for errata, people
should be making changed in the trunk docs. I would much prefer to see
the contributions go there, which can then be verified in the release
process by the testing team and release manager. I am of the opinion
that our docs should be treated as our source code is in order to
maintain quality.
Maybe I'm having troubles seeing the big picture of your suggestion?
Is it:
1. merge mhdoc+mh
2. don't copy release docs, just add release notes for each new version?
No to #1. The idea is to keep MH as is, and expand MHDOC to include
guides and other such information that is important to adopters. Some
pages from MH will move to MHDOC. We provide enough documentation on
MHDOCS to keep adopters out of MH until they are sufficiently
indoctrinated and ready to dive into active development.
I was thinking #2, but I hear your arguments against this approach. See
my earlier idea to consider the install and configure docs as a separate
space for each release.
I'm fine with 1, as we could just make the release docs tree read only
(or only open to release managers to change).
I don't think 2 is efficient, as sometimes there are little updates
(e.g. for this version of ubuntu do x, for that version do y, if using
1.2 on ubuntu version x do something else). I would prefer that our
docs end up being a "manual" for installers to follow for a particular
version. But I understand the link pain - is there a way we can deal
with both the links and have our docs relatively unchanging?
Chris
--
=================
Michelle Ziegmann
Technical Project Manager
Educational Technology Services
University of California Berkeley
_______________________________________________
Community mailing list
[email protected]
http://lists.opencastproject.org/mailman/listinfo/community
To unsubscribe please email
[email protected]
_______________________________________________
