Community contributions to documentation
mlam at ocad.ca
Tue Feb 8 18:47:41 UTC 2011
I really like Scenario #2. Of the few documentation changes I've made, they have all been double-checked before approval. So #2 seems like a natural fit to me.
From: fluid-work-bounces at fluidproject.org [fluid-work-bounces at fluidproject.org] On Behalf Of Cheetham, Anastasia [acheetham at ocad.ca]
Sent: February 8, 2011 10:21 AM
To: Fluid Work
Subject: Community contributions to documentation
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
fluid-work mailing list - fluid-work at fluidproject.org
To unsubscribe, change settings or access archives,
More information about the fluid-work