Submitting & proof-reading articles for documentation (guidelines)

Submit and proof-read articles for the documentation here. Anyone is welcome to contribute!
Locked
westis

Submitting & proof-reading articles for documentation (guidelines)

Post by westis »

Hey people!

Let's moving forward with this documentation thing! Several people have posted suggestions on how we should go abouts and have volunteered to be part of the documentation team. But as I think we really need to get this organized I've posted these straightforward guidelines. Please Matt, Nils and whoever is in the docs team, suggest changes and additions to this or this is how we'll do.

There's now a child forum of the Documentation forum dedicated to the actual articles being written. This is how I'd suggest we'll do:

Who can contribute?
  • For those of you willing to contribute on a regular basis, that is at least every week, post your name in the thread "You'd like to be in the Documentation Team? Post your name here!".
    • Write how long you've used CMS Made Simple and what you're level of knowlede of CMSMS is.
    • Also write what you are willing to contribute with: writing articles for which sections, just reviewing/proof-reading or if you can translate to another language.
    • The Docs team is then keeping a list of who is willing to do what and organizing sub-teams if they find it necessary.
  • Anyone can still write and submit an article, according to the structure of the New Handbook at docs.cmsmadesimple.org. The docs team has the last say on what articles are good enough and complete to be posted on the docs site.
To submit an article:
1. When you start writing an article, write a post in the thread "Articles being written", which will be sticky. This is to avoid double work.
2. Once you've finished with an article, create a new topic called "Article: Name of page" and put your article there. Example: "Article: Installation > Installation wizard". The forum moderator should make this sticky until it's been posted to the docs site. On how to write an article, follow the idea of other posts, like http://forum.cmsmadesimple.org/index.ph ... 674.0.html
3. Then that article will be there for let's say ten (?) days for people to proof-read, before it is uploaded to the docs site.

To make modifications & corrections to an article:

1. Once there is an article in its own thread, anyone can post corrections & modifications in that thread, that is proof-reading. The docs team can always decide what modifications should be taken on.
2. Correct any misspelling, badly structured or incomplete sentences and suggest changes in the text to make it easier to understand also for beginners while not using too many words.
3. Use green text for modifications (misspellings, typos, bad grammar etc.) and red for whatever should be replaced or added.

Translations
Once an article is posted at docs.cmsmadesimple.org it should be considered complete enough for anyone willing to translate to other languages to do so. I think it's good in the long run to have someone coordinate each language. But as for now anyone willing to translate can do so by posting an article in the same way as above, but with the language as the prefix instead of "Article: ". For example: "Swedish: Installation>Installation wizard" instead of "Article: Name of page".

What else can you contribute with?
As Matt has pointed out in this thread (http://forum.cmsmadesimple.org/index.ph ... 692.0.html) there are more ways to contribute to the documentation apart form writing the nuts and bolts stuff, as he calls it. I've taken the following from the just-mentioned thread:
  • Case studies
    This is just a short feature about how you applied CMSMS to solve a problem, how well it worked (including shortcomings), what did the old system ran on (if at all), what other solutions/CMSs you tried (if any), what the client said (if you weren't the client), how you customised it, etc. These really help people figure out if CMSMS is right for them, help give designers and users more ideas and will help some of the guys coding to see how it's working for people other than themselves in more detail.
  • Screenshots
    We also need someone to take lots of screenshots and save them (gif usually results in nice and tiny file sizes) of sections of the admin area, plug-ins, individual buttons in the editor, etc.
Let them articles coming!
Last edited by westis on Tue Sep 27, 2005 12:00 am, edited 1 time in total.
Ted
Power Poster
Power Poster
Posts: 3329
Joined: Fri Jun 11, 2004 6:58 pm
Location: Fairless Hills, Pa USA

Re: Posting & proof-reading articles for documentation (guidelines)

Post by Ted »

Westis,

This looks like a great suggestion to me and should be a decent workflow.  MJH, nils: what do you guys thing?

Ted
gich

Re: Submitting & proof-reading articles for documentation (guidelines)

Post by gich »

Good idea,

keep it up
Locked

Return to “Suggestions, Modifications & Corrections”