[OPEN-ILS-GENERAL] Developer Documentation Organization

[Jane Sandberg]

Agreed!  This looks fabulous.  A big thanks to both of you.

On Mon, May 1, 2017 at 10:43 AM, Terran McCanna
<tmccanna at 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
> tmccanna at georgialibraries.org
>
>
> On Wed, Apr 26, 2017 at 2:27 PM, Daniel Wells <dbwells at 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
sandbej at linnbenton.edu / 541-917-4655
Pronouns: she/her/hers or they/them/theirs