Unifying the Cyrus World

[Nicola Nye]

Hi Patrick,

Just before Christmas we got all the access sorted out and there's now a
copy of docs.cyrus.foundation on cyrusimap.org/new, and it's
auto-updating. It all took longer than we had hoped given FastMail's
exciting few weeks with the DDoS situation. 

When I'm back in the office after the New Year I'll look at what's the
best way to go moving the old site out of the way and whether we
maintain any redirects so any old bookmarks still work for common entry
points. 

Then we can start on the larger task of integrating the docs source back
into the cyrus code source. 

If there's areas that you think need immediate and obvious updating, do
let me know (especially if you can provide pointers to where I can get
the information from, even if it's just links to list threads); I'd
rather ensure that my time is spent easing definite pain points. 

Cheers,

   Nicola

On Mon, Dec 28, 2015, at 01:45 AM, Patrick Goetz via Cyrus-devel wrote:
> Was this issue ever resolved?  I'm still finding the documentation split 
> between cyrus.foundation and cyrusimap.org, and it's incomplete in both 
> places.
> 
> On 09/16/2015 08:50 PM, Nicola Nye wrote:
> > 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