Relaunch of documentation project

[drew]

Hello Nils, everyone else,

I'm glad to see your ambition to refine the document aspect of CMSms. I'm really beginning to love this project but have only been using it for a few months. I would like to help in anyway possible.

In my search for a CMS, I had considered pmwiki. It was mature and capable but needed too much customization thru user installation of plugins/modules. One great aspect of that project was its documentation, especially the modules section. I see that CMSms does have the CMSforge but its content sems spares - some just having a 1 sentence description.

Consider the pmwiki documentation http://www.pmwiki.org/wiki/Cookbook/Cookbook , where modules are categorized and each module has a good description of purpose, function and usage. Most of them have screen shots or links to live examples.

I have found CMSms to be well documented thru its wiki and forum but sometimes I wish there was a better layout. Screen shots and live examples would be an asset in helping users to choose a module without the need for "install to try".

Thank you for your efforts.

-Drew

[versatility]

Well it appears we have consensus and interest in tackling the relaunch of the documentation project.  Time for some practical questions, the biggest of which is should this be a CMS site of a wiki?

I personally have always leaned toward a CMS site, as wikis seem to ring a tremendous amount of visual clutter into the mix and appear to take a lot of work to make attractive and user friendly.  The metadata information on a wiki is usually distracting in page layouts, search results, etc.

However, perhaps we need those wiki functions?  Or could the same basic things, last edited date, author, etc be easily accomplished in CMS?  I use CMS a lot but for the same basic things so I definitely do not know how far it can be pushed.

Once this fundamental decision is made, we need to answer the question of where to install before we can jump.  I think this group is ready to move forward, and in the short term I have server space that could be used, but I tend to think it would be easier to work on this project in it's final home?

Finally, I would like to gather the names of everyone offering help and determine the best way to communicate.  Would anyone (everyone?) be interested in using something like Bascamp for project management and communication?  Does anyone know anything on par with Basecamp that is free?

Thanks,

Diane

[Pierre M.]

Hello Diane,

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. 

As a support team member I very much support your offer and the other offers to work on quality documentation.
Because it should lower the need for support and improve CMSms deployments and use.

The project Leaders work hard on 2.0 (and support and modules and bug fixes and security fixes...) so please be patient ; it is not the first time real life delays things in a spare time project. I can't speak for them but I'm sure their response is coming.

Pierre M.

[Ted]

Pierre just tipped me off to this thread.  I'm really excited that people are interested in taking up this project, as it's really necessary.  I myself have just picked up the ball again in the last week or so starting up on 2.0 development again, so it sounds like we're trying to get out of a bit of a project slump.

We're having a dev meeting tomorrow on irc at 19 GMT (1p EST, 10a PST, 20 most of Europe).  If some of you guys have time, click on that Chat button above and join us.  We're going to be some other topics, but would love to discuss the direction of the documentation project.

If that doesn't work, we can always setup a doc group mailing list so that it's easier to discuss ideas.

Just let me know what you need as far as resources and I'll get it worked out for you.

Thanks!

[westis]

Hi all,

It's really great that people are volunteering to get the documentation in shape! I am in one of these CMSMS down periods that usually last for some time after having been to Kenya... Meaning that I haven't followed the forums very well and haven't accomplished what we decided on the CMSMS Dev Meeting in Copenhagen in September.

That is, what were discussed then is very much in line with what many of you have suggested. But as I am not up to leading this development at the moment it would be fantastic if a team could be formed with this responsibility. The documentation is where the dev team has lacked members the most, so what we took on in Copenhagen was more out of necessity than of reality (apparently...).

As Ted says, would be great if some of you could pop in to the dev meeting tomorrow, so that a team leader could be decided on as well as means of communication to get this project going.

I'm willing to be part of it somehow, but just can't take the responsibility to have any major role at the moment, or I'd just dissappoint people.

Thanks for your offers to volunteers and hope we can get this up and going very soon! And thanks Ronny for directing us busy dev team members to this thread.

/Daniel "westis"

[Nullig]

I'd be happy to contribute to the documentation project.

I have a server that we could use for project management - it has dotProject.net installed, as well as Moodle. I've been building a CMSMS training/demo/sandbox site for the users/admins of the sites I've installed and manage, but it could just as well be shared with this project.

Nullig

[versatility]

So it sounds like things are coming together, which is excellent.  I will do my best to join the meeting tomorrow and onward we go.

It sounds like the next steps are getting organized and making some decisions.  Does anyone have an early input on wiki vs. CMS itself?

[westis]

I'd personally prefer a CMS Made Simple solution. At the dev meeting in September we talked about making a moderated documentation, with possibility for any logged in user (FrontEnd Users?) to comment on each article (and if good content appears in the comments it could be added to the documentation by the documentation team, or simply provide additional tips as Ted wrote), as has been suggested above.

Not only would it be a good way to organize the documentation when only approved documentation team members can update the content (which I think is needed to keep the documentation organised, although anyone of course can suggest additions), it would also show off some more ways to use CMS Made Simple.

Apart from the Comments module, the Questions module could also be used for an FAQ section and possibly the Play module for Flash videos (I think Flash is the best format to use for this, as that is what is viewable by most visitors without having to install additional players, most people have Flash player).

And yet another argument, as also has been suggested above, is that it is not yet another system to learn for those contriburing (that would be MediaWiki in this case).

What hindered the movement from wiki to CMSMS pages has mainly been a lack of decision on the structure of the documentation itself, as this would have to be decided upon before embarking on setting up a new system.

So my suggestions for steps to proceed:
1) Decide on CMSMS pages with modules or wiki
2) Decide on the structure of the documentation (good ideas already suggested in this thread)
3) Setting up a temporary site for adding articles/moving from the wiki
4) Move articles from the wiki/update/add content according to the decided structure (and before that decide who is going to work on what sections)
5) Launch the new documentation officially when it is complete enough to replace the current wiki system (not necessarily entirely complete, but at least with the basics complete)

We can discuss this more tomorrow and after that we know better how to proceed, who will be in the team etc. And for others who read this, of course there will always be need for more people to contribute to this!

Again, thanks all who offer their help. That's what keeps this project going forward, and the documentation is very important in that development.

[Nullig]

Another thought would be to have two sets of documentation, one within the CMS structure, housing the "core" documentation and the other within the wiki to document user contributions - mods, tips and tricks.

A lot of work, I know, but something to consider.

Nullig

[westis]

Yeah, some easy way for users to contribute mods, tips and tricks would be excellent. It probably could be setup with a CMSMS module too somehow.

One other cool thing would be if there would be a special blog devoted to tips and tricks, that one or more persons are responsible for and where user tips could be chosen once a week for example (from the forum, from the user tips section of the documentation etc.).  But that may be overkill and in either way would be more for the future, as the basic documentation of course is more important.

What do others think? A wiki for user tips or using some module for the same purpose, which also may be easier to moderate to keep it structured?

[versatility]

I would love to see CMS all the way through if it could be done for familiarity of use, everything in one place (so to speak), easy to associate and cross link content, etc.  It is also easier (I think) to make CMS attractive and user friendly.

Diane

[versatility]

@westis

Can you elaborate on this statement?

2) Decide on the structure of the documentation (good ideas already suggested in this thread)

While I realize we need a little bit of structure to get started, I was thinking the flexibility in CMS would mean not spending a lot of up front time on this.  It is so easy to move pages around and in the hierarchy, but maybe I am underestimating or overlooking some aspect of this. 

Diane

[westis]

@westis

Can you elaborate on this statement?

2) Decide on the structure of the documentation (good ideas already suggested in this thread)

While I realize we need a little bit of structure to get started, I was thinking the flexibility in CMS would mean not spending a lot of up front time on this.  It is so easy to move pages around and in the hierarchy, but maybe I am underestimating or overlooking some aspect of this. 

Diane

Well, what I meant was a general structure as in User Handbook/FAQ/video tutorials/tips and tricks etc. The current documentation fails already on the main level, I think, as it is difficult to know where to start find the information you're looking for. Like what's the difference between the FAQ and the How To Tutorials sections?

And what goes to the Users section and what goes to the Developers section? When does a user turn developer? Maybe something like Basic and Advanced would be clearer than Users and Developers? In the User Handbook we use three different kinds of users: Editors, Designers and Administrators. But on the first page we use Users (which basically includes these three) and Developers. Many terms that may not be clear to a first-time visitor.

And if I'm a total noob I'm supposed to start with the User Handbook. But that might be difficult to understand as "User handbook" may give the impression of a complete "CMSMS bible" rather than an introduction for beginners.

That kind of discussion would be good to have before embarking on filling the documentation with content, as different contributors may have different ideas of what to put where. Although indeed it is also easy to move pages around, so the structure would need to be flexible in either case and 2 and 3 may go hand in hand.

Just my 2 cents.

[westis]

count me in !

note: the hierarchy of the "admin panel help" should follow what we have now, as the help links inside cmsms admin panel point there... in the wiki, atm...

Welcome back Patricia! Good to see you around a bit more these days.

Indeed a good point to make sure that the help from the admin panel integrates with the site help. With time it would be great to have help pages for each module too, maybe somehow linked with svn if at all possible... Instead of having both Help and Community Help in the Admin panel.

[calguy1000]

I think at tomorrows dev team meeting (which will be of a slightly different format), we'll be electing a new documentation team lead, and hopefully that person will handle gathering a team togeether to develop some documentation that everybody can (and hopefully will) use.