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? (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? 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 -- Christopher Brooks, BSc, MSc ARIES Laboratory, University of Saskatchewan Web: http://www.cs.usask.ca/~cab938 Phone: 1.306.966.1442 Mail: Advanced Research in Intelligent Educational Systems Laboratory Department of Computer Science University of Saskatchewan 176 Thorvaldson Building 110 Science Place Saskatoon, SK S7N 5C9 _______________________________________________ Community mailing list [email protected] http://lists.opencastproject.org/mailman/listinfo/community To unsubscribe please email [email protected] _______________________________________________
