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
>

Reply via email to