Stuart, On Tue, Jan 5, 2010 at 1:00 AM, Stuart Lewis <s.le...@auckland.ac.nz> wrote: > Hi all, > > A few points come to mind: > > - What is the benefit of working this new way?
1.) You don't need commit rights or knowledge of SVN to work on the manual. 2.) The feedback on what your editing is visual and immediate. 3.) If using firefox you can edit the page using the WYSIWYG editor 4.) If using Windows and Office you can edit the content in MS Word. 5.) If using OSX you can edit the content directly in NeoOffice 6.) With the manner in which I integrated the JIRA tickets and recent update into the Home page, you can see an immediate status on what needs to be worked on in the documentation 7.) It is much easier to create new pages and have them included into the documentation. In the docBook version inthe SVN, you would actually need to edit sourcecode and docBook index files to have any new pages. 8.) If there are concerns about reviewing changes to the content, there are permission controls and reviewer plugins for Confluence that enable an editorial review process on the documentation. > - According to the Fedora wiki page you quote, it states that it is a list > of documentation issues that need to be taken care of *prior* to the release, > not after the release. Ok, I missed that thank you... Note I did say I still think we should have a documentation sprint and include a most uptodate pdf or html copy into the distribution. > - I feel quite strongly that working asynchronously would not work. If we're > honest, are we really going to come back and fix the documentation, or will > we start working on the next release which is much more exciting? It is much easier to have others work on the documentation between releases if we operate in this manner. It will be much easier to craft the documentation into something that is actually relevant, 50% of what is in it is irrelevant architectural and functional overviews and not pertinent to actually installing, updating or managing a DSpace instance. It is in this state because it has been isolated behind the "bottleneck" of the commiter gatekeeper role that has crippled the community in the past. IMHO, What I just did in liberating the documentation reflects the real kind of participation we want to have going on in the community. The "we" that will be working on the documentation will be a much larger group then half a dozen active committers, thus you can go off and create the great next new releases while others participate in updating the documentation where appropriate. That is the beauty of asynchronous development processes and lowering barriers to participation. > - Surely it is better to release complete documentation with the release? If > we don't offer full documentation with a release, users won't be able to make > use of the new features. No, the important thing is to have correct, uptodate and relevant documentation available within the community in an easily maintainable location with a low bar for maintenance. The idea that somehow this copy needs to be in the release is a rather antiquated system admin viewpoint. DSpace targets a larger community than just system admins and the documentation should reflect that. > - Releasing complete docs for 1.6 doesn't seem like it will be a problem, so > is there actually a problem with the way we are currently working? I did the work to show this can be managed easier and actually invite participation from the community. I think it was a clear intention that migrating the documentation into docBook was about enabling easier management of the documentation generation process. It was about enabling an exit strategy from the current problems getting participation in the documentation process. If you look at the code for the the current generation of the pdf/etc it is both platform/environment dependent and a overly custom hack (Sorry Brad, don't take that as a criticism, its better than where it was when you started the docBook effort). We should be taking the next final steps to complete this exit process. > - A lot of effort (by the fabulous Jeffrey) has been put in to getting the > documentation up to scratch for 1.6. A lot of time has gone into issues such > as making sure the generated PDF looks good. It feels like a big waste of > time to jump to a new documentation method before the current one has seen > the light of day. And none of that effort is lost! The confluence work actually builds on Jeff's work with getting the docBook cleaner and more valid. Having it be clean and consistent enough to xsl transform was critical to getting it into an appropriate form for adding to confluence. Jeff is the first person I showed this to, and the objective was to actually show how we can liberate him from having to manage the somewhat arduous landscape of this "custom" documentation generation process and instead be able to focus more on the content itself. > - How do we manage versioning? Would the document end up with hundreds of > "in version x you do this, in version y you do that"? No, versions of the documentation would be updated and released... see: http://confluence.atlassian.com/display/DOC/Confluence+Documentation+Home http://confluence.atlassian.com/display/CONF28/Confluence+Documentation+Home http://confluence.atlassian.com/display/CONF27/Confluence+2.7+Documentation+Home Which is not dissimilar to http://fedora-commons.org/confluence/display/FR22DOC http://fedora-commons.org/confluence/display/FCR30 But, we can choose to use spaces for this, or organize the release of various dissemination's in one space. The point is of greatest importance is getting the community that is discovering the best practices for managing DSpace making direct contributions to the documentation. Not bottle-necking it behind the committers with specialized knowledge of how to update the documentation (docBook in SVN repo) or an organization with internalized special processes for releasing it into a static website (http://www.dspacedev2.org/1_5_2Documentation/). Mark -- Mark R. Diggory Head of U.S. Operations - @mire http://www.atmire.com - Institutional Repository Solutions http://www.togather.eu - Before getting together, get t...@ther ------------------------------------------------------------------------------ This SF.Net email is sponsored by the Verizon Developer Community Take advantage of Verizon's best-in-class app development support A streamlined, 14 day to market process makes app distribution fast and easy Join now and get one step closer to millions of Verizon customers http://p.sf.net/sfu/verizon-dev2dev _______________________________________________ Dspace-devel mailing list Dspace-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/dspace-devel
