[CentOS-docs] wiki.centos.org .. what's next ?

Wed Dec 13 10:49:58 UTC 2017
Brian Exelbierd <bex at pobox.com>

On Mon, Dec 11, 2017, at 10:41 AM, Fabian Arrotin wrote:
> On 11/12/17 10:22, Thibaut Perrin wrote:
> > Hello Fabien,
> > 
> > First, thank you for even trying for what seems to be an impossible task :(
> > 
> > Quick points : 
> > - if it was decided not to continue, what would happen to the current
> > wiki ? Dismantled or would it remain as read-only for documentation
> > purpose ?
> > - What about Sphinx <http://www.sphinx-doc.org/en/stable/> ? seems to be
> > frequentely used nowadays
> > - As you mentioned, a solution of the type of github with pull requests
> > for documentation updates might be a solution here. 
> > 
> > There is a wiki feature <https://guides.github.com/features/wikis/> on
> > Github. I don't know to which extend it would fit the needs of the project.
> > 
> > Hope this helps,
> > 
> > Thibaut
> So far there is no decision, reason why I started this thread :)
> I guess our target would be to convert (and sanitize ?) existing content
> anyway as we don't want to lose such content. Then either replacing
> wiki.centos.org with new solution (but trying to keep the same structure
> so that all the things in cache for search engines and/or articles
> pointing to wiki can still work) or move to something different and
> indeed keeping existing wiki.centos.org in Read-Only mode

We've been working on a similar project in Fedora.  We have started by
migrating the top doc pages out of our wiki and into a Pagure (git forge
at pagure.io that we use and you're welcome to join us on) repository
that can be used by our docs.fedoraproject.org builder.  We then marked
these new pages as drafts because many need updates (a problem it sounds
like you won't have).  In the wiki we put redirect links to the new
pages on the docs website.

> I'd like to avoid Github specifically but having something else that
> would permit to use ACO (https://acccounts.centos.org) as auth source. I
> already played with gitea and it works with openid so self-hosted git
> instance using ACO works fine. (but that's a different thread)

/me whispers *Pagure* :P

> We should divide all parts into specific areas. Benefits of using .md
> means being able to switch to something else even later and not be tied
> to $yet_another_tool to generate the web part. (just my idea)

We are using AsciiBinder to build our docs site.  I realize this is
$yet_another_tool, but it is one that several other projects in our
ecosystem and sponsor system are using.  The upstream is amenable to
patches, if needed.  It is opinionated, so you have to decide what
you're willing to let go of and what is a "line in the sand."  One of
those opinions, today, is the use of AsciiDoc.  I have a PoC to use
other markups, but it is not complete.

Let me know if any details on what Fedora is doing would be helpful. 
I'd like to see us work more closely on documentation, especially now
that CentOS SIGs are often building bits that are closer to Fedora than
to CentOS core (as I understand it).