Publishing old guides

[Pete Travis]

On 04/25/2015 10:39 PM, Brian (bex) Exelbierd wrote:
> On Apr 17, 2015, at 7:57 AM, Jeff Fearn <jfearn at redhat.com> wrote:
>
>>>> IMO the main problem you face is the heavy start up cost for contributing. Using git and CI is not substantially less cumbersome for contributors than the current solution. While it may attract a few more people
>>>> like the current contributors, it won't attract new classes of contributors.
>>>>
>>>> You need to make it easy for people to contribute content, and in this day and age that means a web interface; just one that doesn't suck.
>>>>
>>>> What you need is a well curated web-based work flow.
> I agree that curation is critical.  The question in my mind is do we have sufficient people to do curation at today’s volume?  Do we have it for tomorrow’s volume?
>
> Does a git/CI workflow reduce friction enough to increase contributions, but not so much as to overwhelm curation?
>
> Are there alternatives to a curation workflow that we could use instead?  karma?
>
> regards,
>
> bex
>
>
>

A big selling point of using git for me is that it allows us to scale
using existing permissions structures like FAS groups for individual
repos.   Where all branches of all docs should be rw for members of
docs-writers, I'd also like to see repos maintained by SIGs for docs in
their space too.  The general process for adding a package to Fedora
involves a thorough review for viability of the product and compliance
against clearly defined guidelines, and at the end you get a git repo
that you own; that's working quite well, and it could work for docs
too.  These groups could manage their own curation, with due
assistance.  Additionally, the 'merge request' workflow is well
established in the open source community.  On the curation workflow,
https://github.com/pypingou/pagure provides a web-based interface for
change management and feature discussion.  It's built on gitolite, so we
can have branch-based ACLs and other fun things that come with it.  Play
around at http://dev.pagure.org/ with your FAS id.


Keeping docs in abstract markup allows us some flexibility in
presentation too.  Obviously, one can change the CSS of a wiki or add
extensions, but the basic structure remains the same.  However, there's
lots of existing packaged documentation and opportunity for
programatically generated documentation that would seem to lend itself
to the build-on-change structure I've been planning.  Just yesterday in
the Server WG meeting there was some discussion about generating
documentation on the ABIs and interfaces that Fedora Server provides to
develop against, for example.  Anerist could have builders for manpages,
symbols and APIs for libraries, or other types of packaged
documentation, lists of packages in a given Fedora deliverable, SELinux
label and policy mappings, and similar stuff that could be cranked out
on package updates.  That process could end with dumping the content via
python-mwlib, but we'd be opting into the problems around delivering
non-static sites and the design limitations of a wiki - despite having
tooling in place that could progressively generate a static site.

After thinking about it for a while, the problem I was originally
identifying with the wiki wasn't so much of a technical one; it's a
social one.  The Fedora Project does not have a wiki curation culture. 
We shouldn't expect that to happen just because there's a new mediawiki
instance.  We *do* have a strong precedent for establishing solid
guidelines and following through on implementing them, and helping
contributors understand the guidelines and workflow.

Basically, there are lots of ideas to hash over and lots of opportunity
to do something really awesome, and using a web based CMS seems to
effectively limit us to "people opening a browser and typing in the
browser window".

-- 
-- Pete Travis
 - Fedora Docs Project Leader
 - 'randomuser' on freenode
 - immanetize at fedoraproject.org

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.fedoraproject.org/pipermail/docs/attachments/20150429/6198197b/attachment.html>