[OPEN-ILS-GENERAL] Developer Documentation Organization

[Daniel Wells]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://libmail.georgialibraries.org/pipermail/open-ils-general/attachments/20170426/401fb33f/attachment.html>