[OPEN-ILS-GENERAL] Developer Documentation Organization

[Rogan Hamby]

I've only skimmed this but a quick thought related to #2 is that parallel
to new documentation efforts it would be good for someone(s) to go through
a lot of that existing 'dev' and 'technical' content and mark pages with
banners that say things like  "may be out of date", "use at your own risk",
"there be grues here" and that sort of thing.  I did that with the hardware
survey page last year and was pleasantly surprised to see someone else come
along and use that as a prompt to update it.





Rogan Hamby

Data and Project Analyst

Equinox Open Library Initiative

phone:  1-877-OPEN-ILS (673-6457)

email:  rogan at EquinoxInitiative.org
web:  http://EquinoxInitiative.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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://libmail.georgialibraries.org/pipermail/open-ils-general/attachments/20170426/7f653be0/attachment.html>