Well, since I've been working on a few things, here's my $.03 worth (inflation, you know).
I may be hashing it over, but simply put, we are agreeing that: 1. The wiki will be the most current. And during the release cycle, we'll edit there and then generate a hard copy (PDF and statiic HTML). 2. That static copies could be linked from the wki/confluence documentation for historical needs and/or for those working with those previous releases. So, for example, Version 1.6x should be linked in the Confluence pages to the PDF and a HTML set. And when 1.7 is released, we generate the PDF and the HTML and then link from the Confluence page back to th 1.7. release, since in theory we are working towards 1.7x or 1.8. I think we already have a page to link FROM---the release history page--now that isn't mostly easily discovered. I know that! We can **also** create a "previous version" link right up front. There needs to be a preface/splash page from which we can create a TOC and all the links. Yes? --Jeff On Oct 4, 2010, at 5:58 PM, Tim Donohue wrote: > A few quick inline comments... > > On 10/4/2010 4:38 PM, Mark Diggory wrote: >> As for future versioning -- we really need to formalize this >> based on >> what we all feel is best. One possible option may be as follows: >> >> (1) "DSDOC" space >> (https://wiki.duraspace.org/display/DSDOC/DSpace+Documentation) >> -- this >> would be the place were we are *always* working on the latest & >> greatest >> documentation. It could also act as a "splash page" to find all >> past >> DSpace release documentation. So, currently this is working >> towards >> 1.7.0 documentation. We should also be working to "clean up" >> the front >> page and all sub-pages to our liking for 1.7 (It may still need >> quite a >> bit of work.) >> >> (2) When 1.7.0 is released, we can export an HTML or PDF version >> of that >> documentation directly from the "DSDOC" area. We could even put >> this >> into SVN if we wished, or just make it downloadable alongside the >> release. >> >> >> I'm all for a readme with an http link to a version specific page >> in the >> Docs wiki. It would contain links to the static html version, pdf >> version and a link describing where to make suggestions for >> corrections, >> recommendations and/or additions. > > Nice idea. That'd be fine by me as well. > > >> (3) After 1.7, and once we are ready to start docs for a 1.8.0 >> release, >> we'll copy the "DSDOC" space into a "DSDOC1.7" wiki space as an >> archive >> (and as necessary to support any future 1.7.x releases), and the >> "DSDOC" >> area would move towards 1.8.0 docs. At this point, there may be >> some >> double wiki changes required if a single Documentation change >> needs >> fixing in both 1.7.x and the 1.8.x documentation (since they >> will sit >> separately in the Wiki). >> >> >> I think this gets quickly becomes too complex. Recommend static >> publication of docs a release time that does not change, pointer to >> the >> latest bleeding edge docs in wiki if folks want to add read about >> whats >> new. As described above. > > Yea -- I can see your point. The main counter-example I could think > of > was if we happened to be simultaneously working on a 1.7.x bug fix > release while also doing a 1.8.0 release. In that sort of situation, > where you are doing simultaneous releases of different versions, you'd > want your documentation kept separate somehow. But, maybe we just > cross > that bridge if we ever come to it (so far, we've never really done a > simultaneous release like that -- so, I'm probably making this too > complex! :). > > Your idea, Mark, is easier (so, we'd just do #1 and #2 as I had > listed, > and NOT #3 nor #4). Simple is probably best for now. If we ever > needed > to expand to something more complex we could do so later on. > >> (4) Eventually (i.e. years from now) in order to avoid keeping >> around >> tons of old wiki spaces (e.g. DSDOC1.7, DSDOC1.8, DSDOC1.9, >> DSDOC2.0, >> etc) for really old documentation, we'll want to clean up old >> "archived" >> wiki documentation. So, once a space becomes "dormant" or >> "static", we >> can just archive a final version to HTML/PDF and post that static >> version up on the DSpace website. Then we can remove that old, >> dormant >> wiki space altogether. >> >> >> My concern is that this creates the overhead you talk about above, >> rather than getting everyone "rallying" around one location for >> changes >> to docs. >> >> This is just one possible idea for how to handle things. So, if >> there >> are other thoughts on upcoming management of Wiki Documentation >> after >> 1.7, we can definitely add that to an upcoming meeting agenda as >> needed. >> >> Thoughts/ideas welcome, >> >> >> Thanks, Tim, for the great summarization on the topic. >> >> Mark >> > > - Tim > > ------------------------------------------------------------------------------ > Virtualization is moving to the mainstream and overtaking non- > virtualized > environment for deploying applications. Does it make network security > easier or more difficult to achieve? Read this whitepaper to > separate the > two and get a better understanding. > http://p.sf.net/sfu/hp-phase2-d2d > _______________________________________________ > Dspace-devel mailing list > [email protected] > https://lists.sourceforge.net/lists/listinfo/dspace-devel ------------------------------------------------------------------------------ Beautiful is writing same markup. Internet Explorer 9 supports standards for HTML5, CSS3, SVG 1.1, ECMAScript5, and DOM L2 & L3. Spend less time writing and rewriting code and more time creating great experiences on the web. Be a part of the beta today. http://p.sf.net/sfu/beautyoftheweb _______________________________________________ Dspace-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/dspace-devel
