Relaunch of documentation project

[nhaack]

Hi there,

I recently finsihed my first CMSMS site and I consumed a lot of the documentation. And it was not always easy to find the right solutions quickly. I sometimes spent days looking for a hint which was ok for me, no complain in this respect.

However, I'd like to push the documentation to a new level. We already have a lot of stuff, but I'd like to melt it into a cmsms based site gathering all documentations, tutorials and problem solutions into a searchable, well-structured single-point-of-entry site to the amounts of stuff already written, filmed and coded. It includes RSS for documentation updates, problem-of-the-week, documentation-requests, categorized archive of solved issues and cross-references to the forum and forge.

Within the next one or two weeks, I could go for creating a map of what I think should be in the documentation and how it could be structured and would put it here for discussion. When we have agreed on the "to be" status, me and some volunteers could go for finding the documentation we have for the single topics and build-up the "documentation portal".

The above is just an idea for discussion here, what do you think of it?

regards
nils

[cubix]

how about concentrating your efforts on the current wiki.

rather than having information in the forums, wiki and an external site, it could be difficult to actually track down where the most up to date information is..

also there is already a section for visual tutorials in the wiki.

however, if your still wishing to persue a new documentation site, then go for it!

[nhaack]

Hi Cubix,

I was thinking of something integrated into cmsmadesimple.org. It could also be the wiki. I just thought that cmsms could be used to also show off its features in the same place. The forum would still be the place for the more comunicative part. But I think it would be nice if all fixed stuff and confimed solutions would be close to the actual documentation.

regards
nils

[cubix]

i came across somones dev site (very recently) and ill have a look for it when i get home..

another forum member has started a cms site with an explanation of each module with screen shots and information about how it works etc..

i like the idea of a central place for finding information which is why i suggested developing the wiki further, and the idea of a wiki is that anyone can develop and add to the information in the future.

there has been lots of talks about a sandbox or test install but due to the security issues it would be hard to maintain therefore i think people should be forwarded to http://opensourcecms.com/index.php?opti ... iew&id=452

[Ted]

Honestly, I think the wiki is in some sad shape.  Not only is it one more thing to maintain (mediawiki), it also allows for everything to be a mess.

Personally, I would rather see a more "official" documentation project.  Something where someone is in control and people have the ability to comment on each page (like the php docs).  The maintainer would then be able to modify based on those suggestions, or people would read those comments for tricks and other little things not covered.

It's a win-win, but it does take a documentation group (or person) to be pretty dedicated to keep up to date.  I'd love it if someone took this job on, as it's something that's seriously lacking and probably one of the main reasons why CMSMS isn't more successful.  But it's a lot to ask of someone...

[Pierre M.]

Hello all,

I agree that if documentation were better there would be less time lost in the forums and more time for 2.0 and current release support.

I second Ted on the "official documentation project" : a (dedicated team) maintained content, improved by suggestions, solved issues, comments (from the community). The last CMSms team meeting has agreed on such a project, using CMSms with modules such as questions and comments. I like the idea of the community free to contribute and the documentation team organizing all the contributions (selecting, merging, sorting, shaping...). Yes, it is a job to do this.

Let me list what I find good ideas from all what you have said so far :
a cmsms based site
documentations
tutorials, films, code samples
problems and solutions
searchable
well-structured (not easy to match everyone's mind) single-point-of-entry (but powerfull)

I'd like to stress this single-point-of-entry practice : I think it is a must have. It is why "the wiki is in some sad shape" today. I often complain of people refering to the doc but not the same I'm refering to even on the same topic : we can't understand each other, it is pain. I vote single-point-of-entry. Of course there are things that can be overviewed then explained more deeply, the overview is the section header of the other parts.

Here is (part of) my opinion on "a map of what (...) should be in the documentation" : informations about the CMSms project (teams, how to contribute/join, releases, awards, show off...) not only the CMSms product (Core, modules, forge...)

Last point : the user oriented but most of all task oriented manual. (ouch, I'm feeling old in this project

Pierre M.

[cubix]

well if there is going to be a relaunch.

a single point entry sort of documentation centre.

im happy to lend a hand as a contributer, im not the greatest technical writer (as ive found writing a training manual for my work)

but when it comes to re organising and compiling relevant information, im keen!

[nivekiam]

Hello all,

I'll help out where I can.  I don't know how much time I'll be able to commit to anything, but I'll help.

With CMSms can users submit content and the "moderators" or "overlords" of the documentation team sort through that submitted content and 1) clean it up if needed then 2) categorize it and put it in a logical place?

I like the idea of using CMSms for this, I think it would be the perfect tool to deliver the content.  The wiki bases solutions always seem to either fall apart or the projects I've seen with good documentation on a wiki have quite a few people dedicated to handling it as well as having a lot of users submitting content.  Which alway seems to be the problem.

[Pierre M.]

Humm... has a documentation team "overlord" be seen in the last two months ? (S)he has volunteers to welcome here. (and others contributing to the wiki)

Managing something on spare time is not easy. May be booking two hours every four days helps ?

Pierre M.

[versatility]

I would volunteer to be a documentation overlord.  I am very very challenged by the current format, and have often considered creating my own CMS site with notes and examples gleaned from the forums and current documentation.  My life experience as a director of application development teams and then a designer.  I have done large scale end user documentation projects.

I believe there are lessons to be gleaned here from two sources - Wordpress has great documentation, a bit messy, but I have always found what I need.  They had a real dedicated focal point resouce in Lorelle.

Another inspiration or pattern to follow is Magento.  There documention is already a pleasure to read.

I'm willing and able, but I have no idea how to help.  The wiki makes my head hurt and I feel a fresh start is in order.

[DaveW]

There you go devs.  Documentation Overlord(s) volunteer has arrived.

Hope you all can get a meeting together and get a strategy put together.  Then maybe volunteers could be solicited according to a proposed direction.  I am available to help.

[versatility]

Logistical notes - I am in southeast U.S. on EST - and do not have a clue about IRC.

[DaveW]

versatility,

I am on SE / EST as well.  Florida.  FYI.  Here is more info on IRC.

http://www.cmsmadesimple.org/support/irc

Dave

[versatility]

I don't really know what practical next steps are, or if the dev team is even interested in my offer.  This is the third time I have offered services for this project, the previous two by email, and then just go nowhere and I am not sure why. 

[nivekiam]

I'm in the PST.  I don't know where I can help.  But will help out where I can.  I don't have much, if any time to chat in the forums or on irc during the day.  So it would pretty much be 7pm PST and later for me on the week nights and most Saturdays, Sundays can be spotty for me.

I don't think I would be reliable enough in being able to make meetings to be part of any type of core documentation group.  But if tasks are created I could volunteer and help out where I could.

I can create tutorials, write up user guides, etc.  We might even be able to start by taking the current wiki, creating a CMSms based site and porting the content over.  Then work on cleanup, expanding, organizing, etc.

This might be something we need to jumpstart ourselves to get started.  I'll PM my email if you want to send some emails back and forth.