Agreed! This looks fabulous. A big thanks to both of you. On Mon, May 1, 2017 at 10:43 AM, Terran McCanna <tmcca...@georgialibraries.org> wrote: > Dan and Remington - I am so happy that you are tackling this project! It > will be of great assistance to any new developers in the community and to > those of us who are working to expand our knowledge. > > Thank you! > > Terran McCanna > PINES Program Manager > Georgia Public Library Service > 1800 Century Place, Suite 150 > Atlanta, GA 30345 > 404-235-7138 > tmcca...@georgialibraries.org > > > On Wed, Apr 26, 2017 at 2:27 PM, Daniel Wells <dbwe...@gmail.com> wrote: >> >> 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 > >
-- Jane Sandberg Electronic Resources Librarian Linn-Benton Community College sand...@linnbenton.edu / 541-917-4655 Pronouns: she/her/hers or they/them/theirs