Community contributions to documentation

[Cheetham, Anastasia]

Hello, all,

One of the requirements we have of a new documentation system is that it allow the community to contribute to the documentation. The various options I've been considering offer this ability to varying degrees. I'm interested in feedback on these different degrees: are they all equally acceptable, or do some offer too high a barrier?


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.


These scenarios offer various advantages and disadvantages, and I'd appreciate hearing everyone's thoughts. Let me know if you have any questions about how these scenarios would work.

-- 
Anastasia Cheetham     Inclusive Design Research Centre
acheetham at ocad.ca            Inclusive Design Institute
                                        OCAD University