On 18/10/2008, at 5:35 AM, alan mcclellan wrote: > * *Versioning of wiki content* > o Alan framed discussion.... there seems to be implicit > requirement that we produce a PDF version of any content > that is in wiki format. Questions: What are real > requirements for creating static version of a wiki-based doc > and what do we need to do to track to a release?
I think the real requirement is having a static version which is unlikely to change, but has a strong association to a particular milestone release - ie. 'snapshot' of the development wiki for 2008.11, then continuing work on the wiki for 2009.04. PDF is 'nice to have' but probably not necessarily a requirement. > o Alan asked again what's behind the compulsion to provide a > PDF snapshot of a wiki doc. Kelly thought there might be > reasons to do this for Support. (Paul Kasper noted that any > static copy should point to the "living" document as the > latest and greatest content, since a static copy could very > quickly be out of date. Alan noted there have been legal > requirements, specifically with regard to submitting > copyright requests with the federal government, which had to > be done for 2008.05. Kelly said she did not anticipate need > to do this for 2008.11. Only for major new releases. (Alan > cheered this news. smile Kathy wondered if there were any > other legal requirements. Alan to ask Legal. (Done -- Jeff > Osteen says that outside of the copyright filing scenario, > he knows of no requirement from legal that we produce a PDF) From my point of view, I think there's real value in creating a static copy of the documentation. As we produce each 6 month release, I think it's important for users to know what documentation applies to what release. > o Cindy Swearingen noted that Solaris docs are currently > considered "continuously updated docs." Paul made reference > to a document that spells out procedural guidelines for > continuously updated docs. Shouldn't wiki-based docs be > viewed similarly? Alan asked Paul to share the guidelines > doc. (Done.) I think we can continue to have 'continuously updated docs' - there's nothing stopping us from snapshotting some content, then working on things for 2009.04 (or having a set of 'in development' documentation). > > o Kelly suggested we get inputs from Glynn Foster (Marketing). > Alan will follow up with Glynn. > o Kelly also asked how other distributions handle versioning. > Cindy and Alta did some lookups during and discussion and > reported the following: > + Ubuntu - Documentation for Ubuntu > (https://help.ubuntu.com/) shows tabs to access > documentation for earlier releases. (Alan noted that > OpenSolaris > <http://infoshare.sfbay/twiki/bin/view/Main/OpenSolaris > > > doc community site intends to provide access to both > current and previous releases. Will see first > iteration of this in 2008.11.) Note that there is a > "community docs" tab right next to the "release > version" tabs. Going to the wiki docs, it's unclear > what version of Ubuntu the community docs are intended > to support. Ubuntu have done it like I think we should ie. a given snapshot of their documentation is relevant to a particular release. Obviously there are bits of it that may be appropriate to past or future release, but it's a continuous document in terms of management at the source. As the release is made, they snapshot their documentation, then work on the source for the next release. > Hopefully at least part of this mail makes sense ;) Glynn
