Community contributions to documentation

Colin Clark colinbdclark at gmail.com
Wed Feb 9 14:20:17 UTC 2011


Hi Anastasia,

I think there is a huge value to favouring openness wherever possible. We're a small community, and any contribution--regardless of how big or small--is huge for us.

My experience contributing to the Mozilla Developer Network (MDN) documentation sprint a few weeks ago reminded me just how valuable an open wiki can be for the documentation process. It was so easy to contribute: I signed up for an account and wrote some stuff. Sheppy and Janet and the other documentation leads at MDN were there to answer questions and help with edits, styling, and more. As a contributor, it felt really approachable and satisfying--my contributions were as equally welcome as anyone else's.

As long as the wiki has change tracking and notifications, I don't think there's a quality risk. We can easily see changes and tweak them as needed. In fact, I think there's a quality benefit to a wiki--people can casually contribute to documentation when they see errors or have suggestions. We've certainly benefitted from editing angels in the past, and I can't think of any examples where things got worse, only better.

In contrast, the alternative scenarios you've outlined involve putting us in a position of being the bottleneck, having to review and publish any change before others can benefit from it.

Colin


On 2011-02-08, at 10:21 AM, Cheetham, Anastasia wrote:

> Scenario 1: A wiki
> ------------------
> A wiki of some kind obviously makes it very easy for anyone in the community to edit the documentation. Edits would become public immediately, and would need to be double-checked occasionally by the core team.
> 
> Scenario 2: Structured markup in Git
> ------------------------------------
> In this scenario, the source for our documentation would consist of structured markup (i.e. a wiki-like syntax) in plain text files in Git. The published HTML would be produced from these source files. This would allow the community to make changes to the docs by forking the repository and submitting a pull request. Changes would not become public until new docs are generated by the core team.
> 
> Scenario 3: XML in Git
> ----------------------
> This scenario would be the same as the previous one, but the source files would be XML and not a wiki-like syntax.
> 
> Scenario 4: Wordpress as CMS
> ----------------------------
> This scenario involves using Wordpress as the interface for creating and editing documentation. The XML stored by Wordpress is processed to produce HTML for the docs. We would allow the community to have access to the Wordpress instance for contributions, and the core team would be responsible for reviewing the contributions and producing the final output.

---
Colin Clark
Technical Lead, Fluid Project
http://fluidproject.org




More information about the fluid-work mailing list