<!DOCTYPE html>
<html>
<head>
<title></title>
</head>
<body><div>Dear Cyrus folks,<br></div>
<div>&nbsp;</div>
<div>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.&nbsp;<br></div>
<div>&nbsp;</div>
<div>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.<br></div>
<div>&nbsp;</div>
<div>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.<br></div>
<div>&nbsp;</div>
<div><span class="size" style="font-size:16px"><b>Issues</b></span><br></div>
<div>&nbsp;</div>
<div>1) Branding<br></div>
<div>&nbsp;</div>
<div>We are currently split across two internet presences: cyrus.foundation and cyrusimap.org. This is confusing. We should only have one.<br></div>
<div>&nbsp;</div>
<div>The cyrus.foundation domain name is not of real use as there is a pre-existing entity (The Cyrus Foundation) of the same name.<br></div>
<div>&nbsp;</div>
<div>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)<br></div>
<div>&nbsp;</div>
<div style="margin-top:0px;margin-right:0px;margin-bottom:0px;margin-left:0px;padding-top:0px;padding-right:0px;padding-bottom:0px;padding-left:0px;outline-style:none;outline-color:initial;outline-width:initial;color:rgb(43, 43, 43);font-family:'Helvetica Neue', arial, sans-serif;font-size:13px;font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;line-height:14.7727px;orphans:auto;text-align:start;text-indent:0px;text-transform:none;white-space:normal;widows:1;word-spacing:0px;-webkit-text-stroke-width:0px;">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.<br></div>
<div>&nbsp;</div>
<div>2) Docs logistics<br></div>
<div>&nbsp;</div>
<div>The docs repo is separate to source which is causing friction keeping man pages updated. <br></div>
<div>&nbsp;</div>
<div>We want man pages in two formats: *nix for actual man pages to ship and install with cyrus, and html for web presentation.<br></div>
<div>&nbsp;</div>
<div>Nice to have: ship a snapshot of all current docs (not just man pages) along with source distribution.<br></div>
<div>&nbsp;</div>
<div>3) Sphinx vs wiki<br></div>
<div>&nbsp;</div>
<div>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.<br></div>
<div>&nbsp;</div>
<div>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.<br></div>
<div>&nbsp;</div>
<div>&nbsp;</div>
<div><b><span class="size" style="font-size:16px">Possible solutions</span></b><br></div>
<div>&nbsp;</div>
<div>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.<br></div>
<div>&nbsp;</div>
<div>There are a number of @cyrus.foundation email accounts that would need to be dealt with for Chris Davies' testing.<br></div>
<div>&nbsp;</div>
<div>Option 1: Single domain, unify git repos, use sphinx everywhere<br></div>
<div>--------------------------------------------------------------------------------<br></div>
<div>&nbsp;</div>
<div>Moving the git repo to cyrusimap (or anywhere) isn't hard. (a job for Bron)<br></div>
<div>&nbsp;</div>
<div>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.<br></div>
<div>&nbsp;</div>
<div>Put sphinx on cyrusimap to replace the wiki. This requires either:<br></div>
<ol><li><div>working out how to set up the existing generated docs for use with sphinx, <br></div>
</li><li><div>or make all the stuff in cyrus-imapd/doc into rst so it works with sphinx. We can still ship the built html.<br></div>
</li></ol><div>&nbsp;</div>
<div>Option 2: Single domain, unify git repos, use wiki for docs<br></div>
<div>-----------------------------------------------------------------------------<br></div>
<div>&nbsp;</div>
<div>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). <br></div>
<div>&nbsp;</div>
<div>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.<br></div>
<div>&nbsp;</div>
<div>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)</div>
<div>&nbsp;</div>
<div>Option 3: Single domain, separate git repos, use sphinx for docs<br></div>
<div>----------------------------------------------------------------------------------<br></div>
<div>&nbsp;</div>
<div>Move all services to cyrusimap.org, but still leaves us with all the docs logistics and sphinx and wiki chafe points. Not recommended.<br></div>
<div>&nbsp;</div>
<div><b><span class="size" style="font-size:16px">Recommendation</span></b><br></div>
<div>&nbsp;</div>
<div>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.<br></div>
<div>&nbsp;</div>
<div><b><span class="size" style="font-size: 16px">What Now?</span><span class="size" style="font-size: 16px"><br></span></b></div>
<div>&nbsp;</div>
<div>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.<br></div>
<div>&nbsp;</div>
<div>&nbsp; &nbsp;Nicola<br></div>
<div>&nbsp;</div>
<div>&nbsp;</div>
<div>&nbsp;</div>
<div>&nbsp;</div>
<div>&nbsp;</div>
<div>&nbsp;</div>
<div>&nbsp;</div>
</body>
</html>