Islandora Documentation- Contemplating a move from Confluence to GitHub

[Melissa Anez]

Hi all,

One of the discussions we had at Friday's Islandora Roadmap meeting was over the possibility of taking our user documentation and moving it from its current home in a Confluence wiki [1] to put it all into GitHub, with a mix of general documentation stored with the core Islandora module [2] and module-specific documentation living in the repos of the appropriate modules.

This would be a major restructuring of how we do docs, so it's definitely something that needs input from the community before we go any further. We need to know how you're using the docs, what you like and don't like about the current set up, any pros and cons you see to either solution. In general, what to you think of the move and is it something that would make Islandora's documentation better or worse for you and your institution?

We identified a few pros and cons, and we're hoping you can add to both lists:

Pros for moving to GitHub:

1. Easier to create new accounts (currently our wiki does not allow new users to make their own accounts; they must be requested from an administrator)

2. Faster performance.

3. Docs would be more closely tied to their modules and to the code.

4. More Git users=Maybe more contributors in the future

Cons:

1. Big migration and restructuring of the docs (maybe this is not a con, though - we'd get a chance to re-examine how the docs are structured and maybe fix some long standing issues)

2. We have a quick & easy method to export confluence docs into a PDF or printed book. There may be ways to replicate this in GitHub, but we're not sure of a method right now.

3. Versioning becomes difficult. Confluence docs are versioned by the Islandora version number, so you can look up the docs for the version you have installed. We're not sure exactly how to handle this in Git just yet.

4. Maybe not as easy for new users to navigate. We could mitigate this by keeping a table of contents on islandora.ca.

All of this is also tied to a discussion about taking our issues/ticket handling and going from JIRA [3] to GitHub as well, for one-stop-shopping. Many of the pros and cons are the same, with some extra complications concerning the spread of issues across multiple repos versus the single venue for all components that we have in JIRA.

Thanks for your feedback,

Melissa

[1] https://github.com/Islandora/islandora/wiki/Roadmap-Meeting-March-7-2014-2pm-AST

[2] https://github.com/Islandora/islandora

[3] https://jira.duraspace.org/browse/ISLANDORA

[Nigel Banks]

Github++

[Ernie Gillis]

As a new user and trying to wrap my head around what is out there and what is stable / development / bleeding edge / etc, I would just like to see it centralized.

I don't necessarily have a preference one way or another, as long as it's centralized. If the navigation is a little problematic, that's a trainable issue. If a user can't download, or finds too many or not enough options, then that's a product issue.

Just my $0.02 :)

[Peter Murray]

I think you’ve laid out the pros and cons nicely.  I think the versioning con is a particularly important one, especially for a project like this one where HEAD is moving as fast as it is.  It will be important for released versions of the modules (e.g. ‘7.x-1.2’) to have a stable set of documentation as the project makes forward progress in other areas.

I’ve poked around a little bit for tools that can help with GitHub documentation integration.  One that I found is “Read the Docs” (http://read-the-docs.readthedocs.org/en/latest/index.html), which uses GitHub webhooks and text files in Restructured format, and is used heavily by the Python folks.  Pros: would bring all of the documentation together with versioned/translated branches.  Cons: adding another language (Python) and markup format (Restructured) to our toolkits.

Peter

--
You received this message because you are subscribed to the Google Groups "islandora" group.
To unsubscribe from this group and stop receiving emails from it, send an email to islandora+...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
Peter Murray
Assistant Director, Technology Services Development
LYRASIS
Peter....@lyrasis.org
+1 678-235-2955
800.999.8558 x2955

[Nick Ruest]

Definitely agree. I fear that the documentation tied to specific version
will be the show stopper. But, Github project wikis are actual git
repos[1]. You can can clone them, do whatever you can normally do with
git and lovely, lovely markdown.

The other thing we could totally do, is take advantage of Github
pages[2] for the project. It would take a little bit of planning and
work to implement, but I'm confident we could pull together as a
community and do this. Who would be interested in a documentation
migration working group? :-)

Thinking ahead to possibly move tickets over to Github, I dug up the
Hydra community discussion[3] about this issue. I might be worthy
following up on that thread, and saying that we're thinking of doing
this as well, and asking how it has worked out for them.

-nruest

[1] http://stackoverflow.com/questions/15080848/how-do-i-clone-a-github-wiki
[2] http://pages.github.com/
[3] https://groups.google.com/d/msg/hydra-tech/A7FFFjgF0Ow/8qhrpskXKxwJ

On 14-03-12 08:16 PM, Peter Murray wrote:
> I think you’ve laid out the pros and cons nicely. I think the
> versioning con is a particularly important one, especially for a project
> like this one where HEAD is moving as fast as it is. It will be
> important for released versions of the modules (e.g. ‘7.x-1.2’) to have
> a stable set of documentation as the project makes forward progress in
> other areas.
>
> I’ve poked around a little bit for tools that can help with GitHub
> documentation integration. One that I found is “Read the Docs”
> (http://read-the-docs.readthedocs.org/en/latest/index.html), which uses
> GitHub webhooks and text files in Restructured format, and is used
> heavily by the Python folks. Pros: would bring all of the documentation
> together with versioned/translated branches. Cons: adding another
> language (Python) and markup format (Restructured) to our toolkits.
>
>
> Peter
>
> On Mar 10, 2014, at 10:33 AM, Melissa Anez <meliss...@gmail.com

>> by keeping a table of contents on islandora.ca <http://islandora.ca/>.

>>
>> All of this is also tied to a discussion about taking our
>> issues/ticket handling and going from JIRA [3] to GitHub as well, for
>> one-stop-shopping. Many of the pros and cons are the same, with some
>> extra complications concerning the spread of issues across multiple
>> repos versus the single venue for all components that we have in JIRA.
>>
>> Thanks for your feedback,
>> Melissa
>>
>>
>> [1]
>> https://github.com/Islandora/islandora/wiki/Roadmap-Meeting-March-7-2014-2pm-AST
>> [2] https://github.com/Islandora/islandora
>> [3] https://jira.duraspace.org/browse/ISLANDORA
>>
>> --
>> You received this message because you are subscribed to the Google
>> Groups "islandora" group.
>> To unsubscribe from this group and stop receiving emails from it, send
>> an email to islandora+...@googlegroups.com

>> <mailto:islandora+...@googlegroups.com>.

>> For more options, visit https://groups.google.com/d/optout.
>
>
> --
> Peter Murray
> Assistant Director, Technology Services Development
> LYRASIS

> Peter....@lyrasis.org <mailto:Peter....@lyrasis.org>
> +1 678-235-2955
> 800.999.8558 x2955
>

> --
> You received this message because you are subscribed to the Google

> Groups "islandora-dev" group.

> To unsubscribe from this group and stop receiving emails from it, send

> an email to islandora-de...@googlegroups.com
> <mailto:islandora-de...@googlegroups.com>.

> For more options, visit https://groups.google.com/d/optout.

--

-nruest