[OPEN-ILS-GENERAL] Developer Documentation Organization

[Galen Charlton]

Hi,

On Wed, Apr 26, 2017 at 2:27 PM, Daniel Wells <dbwells at gmail.com> wrote:
> 1. Use the wiki

+1

> 2. Create a new namespace, "documentation:developer"

+1

> 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.

0, as I think that numbering the pages would make a stronger statement
about a One True Ordering of topics (as opposed to a bunch of
potential orderings whose usefulness depends on where a given person
is starting from) than may be warranted. That said, I have no strong
objections to organizing the material in the form of a book-like thing
if that works for you.

> We could also then use a plugin to apply 'next' and
> 'previous' buttons to allow for effective browsing from section to section.

Is there a particular DokuWiki plugin you have in mind?

> 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.

0; I think this should be evaluated on a page-by-page basis, and I
reiterate my concern expressed above about insisting on a single
narrative flow.

> 5. Capture external content into evergreen-ils.org

+1

Regards,

Galen
-- 
Galen Charlton
Infrastructure and Added Services Manager
Equinox Open Library Initiative
phone:  1-877-OPEN-ILS (673-6457)
email:  gmc at equinoxInitiative.org
web:  https://equinoxInitiative.org
direct: +1 770-709-5581
cell:   +1 404-984-4366