Hello all, A bit later than hoped, here are an assortment of small proposals for (re-)organizing the developer documentation on the Evergreen wiki. The overall goal is to develop what we have and what will come into a useful and cohesive corpus.
1. Use the wiki As mentioned in our talk, after considering various options already in use by our community, we believe the wiki gives us the best cost-to-benefit for this particular project. Some of the reasons we use more purpose-built documentation for our end-user docs (tracking versions, print-friendliness) do not have quite the same luster here, and the level of developer comfort with using and editing the wiki is quite high. We can revisit this later on, of course. 2. Create a new namespace, "documentation:developer" The existing 'dev' namespace contains a mixture of history, process information, collaborative pages, and documentation. There is an existing 'documentation' namespace with very small sub-spaces for 'technical' and 'tutorials'. None of these areas seem particularly ripe to build on, and we want to avoid hijacking any space in order to preserve existing content. 3. Use a numbering scheme for naming pages in this new namespace To work within the natural structure of the wiki, yet still give the text as a whole a logical learning sequence, we suggest that the pages in this namespace be numbered with a simple "Chapter-Section" style, specifically ##-## (e.g. 01-01). Using "dash" as the main delimiter allows for the possibility of decimal expansion as needed (e.g. 02.2-01) while still ordering correctly. We could also then use a plugin to apply 'next' and 'previous' buttons to allow for effective browsing from section to section. Or, to go in a slightly different direction, we could have each "Chapter" be a sub-namespace. Doing so would add additional structure, but also complexity. If anyone has a great reason why one approach is clearly superior, please advise. 4. Move existing content into this new namespace/structure While we could simply link out to other parts of the wiki, in many cases we will benefit from putting more content under one roof. This will encourage more thought for the overall narrative flow of the text, and will provide very helpful context when deciding to update or archive a page. Source pages will be left in place for link preservation, but will be marked as "legacy" with an added link to the new home. 5. Capture external content into evergreen-ils.org Many of the resources we link to, particularly emails and older presentations, are held on sites which may disappear without warning. For instance, we already lost the entire 2012 conference website, and have yet to recover many of the presentations from it. While a page can and should link out to external pages for reference, we should also attempt to ensure that we copy files and salient text onto the community www server for preservation. The rough outline and planned overall structure, as shown briefly during our talk, can be viewed here: http://library.calvin.edu/devdocs_project/doku.php Feedback, as always, is welcome. We hope to move on this plan in earnest as the semester winds to a close in the next few weeks. Sincerely, Dan