Unifying the Cyrus World

[Nicola Nye]

Dear Cyrus folks,

After nominally completing the migration of the docs from the wiki at
cyrusimap.org onto the sphinx repository at docs.cyrus.foundation, I
worked out there was a whole bunch of existing services at cyrusimap.org
that were non-trivial to relocate. Which, after some discussion at the
Cyrus hangout, we felt that retaining cyrusimap.org as our primary (and
sole) presence made more sense.

Equally, there are some documentation issues that are affected by our
current straddling of two worlds. Read on for a discussion of the issues
and down to the options and recommendation.

I'd love to have your input (particularly Nic Bernstein on the docs
angle!) if you agree or disagree so we can make for a more unified
Cyrus presence.

*Issues*

1) Branding

We are currently split across two internet presences: cyrus.foundation
and cyrusimap.org. This is confusing. We should only have one.

The cyrus.foundation domain name is not of real use as there is a pre-
existing entity (The Cyrus Foundation) of the same name.

Swapping our internet domain name presence from cyrusimap.org to
cyrus.foundation is no longer a significant driver as a result,
especially as cyrusimap.org is already indexed and linked to around the
net and is unambiguous. (Yes, Cyrus does so much more than just imap,
but it's the primary association)

Currently services are split across the two domains - git repos,
phabricator and authoritative online docs on cyrus.foundation, while
downloads, bugzilla and generated docs are on cyrusimap.org.

2) Docs logistics

The docs repo is separate to source which is causing friction keeping
man pages updated.

We want man pages in two formats: *nix for actual man pages to ship and
install with cyrus, and html for web presentation.

Nice to have: ship a snapshot of all current docs (not just man pages)
along with source distribution.

3) Sphinx vs wiki

We have been working towards making the content on cyrus.foundation to
be the most up to date. This is using Sphinx, which allows us to
generate, from the same source, man pages as well as web pages. (And
even pdf or single page html). So we get nicer output format options.
Clearer history in the git log than you get from wiki.

Cyrusimap docs are held in mediawiki. Not so great for man pages. But
it's much easier for third party contributor to pitch in and help out:
they don't need to learn rst, they don't need a phabricator account,
they don't need to navigate git.


*Possible solutions*

In all cases it seems clear that we should stop using the
cyrus.foundation domain and ideally services that are hosted there be
shifted to live alongside cyrusimap.org for ease of access.

There are a number of @cyrus.foundation email accounts that would need
to be dealt with for Chris Davies' testing.

Option 1: Single domain, unify git repos, use sphinx everywhere
----------------------------------------------------------------------
----------

Moving the git repo to cyrusimap (or anywhere) isn't hard. (a job for
Bron)

Get rid of separate cyrus-docs repo. Put cyrus-docs stuff back inside
cyrus-imapd/docs for easier man page generation and tagging of docs
versions with source, and shipping of current docs with source.

Put sphinx on cyrusimap to replace the wiki. This requires either:
 1. working out how to set up the existing generated docs for use
    with sphinx,
 2. or make all the stuff in cyrus-imapd/doc into rst so it works with
    sphinx. We can still ship the built html.

Option 2: Single domain, unify git repos, use wiki for docs
-------------------------------------------------------------------
----------

Put sphinx on cyrusimap.org just for generating man page html. Leave the
existing wiki where it is for documentation. (Requires porting the page
updates I made from cyrus.foundation onto the wiki).

This means the only thing left in the cyrus-docs git repo would be the
man pages, at which point it makes more sense to put them back into the
cyrus-source repo.

We can still ship docs with the release if we tie in a wiki export into
the release-building process. (A job for Ellie and I)

Option 3: Single domain, separate git repos, use sphinx for docs
------------------------------------------------------------------------
----------

Move all services to cyrusimap.org, but still leaves us with all the
docs logistics and sphinx and wiki chafe points. Not recommended.

*Recommendation*

I am leaning towards suggesting option 2. Anything that makes
documentation support easier is a good! But we'd still like to retain
the usefulness of sphinx for generating two output formats from single
source man pages.

*What Now? *

Discuss! I imagine those folks who come to the Hangout in the next few
meetings will kick it around and we'll come to a decision next week.

Nicola






-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.andrew.cmu.edu/pipermail/cyrus-devel/attachments/20150917/1a876695/attachment.html