Re: [OPEN-ILS-GENERAL] Developer Documentation Organization

[Galen Charlton]

Hi,

On Wed, Apr 26, 2017 at 2:27 PM, Daniel Wells  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:  g...@equinoxinitiative.org
web:  https://equinoxInitiative.org
direct: +1 770-709-5581
cell:   +1 404-984-4366

Re: [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
 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
> tmcca...@georgialibraries.org
>
>
> On Wed, Apr 26, 2017 at 2:27 PM, Daniel Wells  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
sand...@linnbenton.edu / 541-917-4655
Pronouns: she/her/hers or they/them/theirs

Re: [OPEN-ILS-GENERAL] Developer Documentation Organization

[Terran McCanna]

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

Re: [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:  ro...@equinoxinitiative.org
web:  http://EquinoxInitiative.org

On Wed, Apr 26, 2017 at 2:27 PM, Daniel Wells  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
>