On 04/25/2015 10:39 PM, Brian (bex) Exelbierd wrote:
On Apr 17, 2015, at 7:57 AM, Jeff Fearn <jfearn@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@fedoraproject.org