Personal tools
You are here: Home Archive 2005 December 04 Task-oriented Documentation
Document Actions

Task-oriented Documentation

by Alan Runyan last modified December 04, 2005 - 11:43
Filed Under:

Ofer randomly emails me things he finds on the net. Today I had some time to read the blog posting he sent to me which was a guy ranting about the status quo in Open Source CMS. While I think he missed the point with Plone; he got one thing right.

I'm not into blogs.  When I'm on the computer these days - there is no time for faffing about with weblogs.  I have my set of weblogs - I dont even have a RSS client that rolls them up.  I goto them manually.  Thats how lame I am.  Ofer pointed me to a weblog entry where this guy is fed up with open source cms systems.  Buddy, we all are fed up with the state of CMS that is why the Plone project is trying to fix it.

So this guy's major complaints are:

Make it easy to install. --

I think Plone is a winner in this category.

Make it easy to get started. --

I think Plone needs to focus on this

Write task-based documentation first.

I think this is critical for Plone to take over commercial markets.

Separate the administration of the CMS from the editing and managing of content.

I explain this below.  Basically out-of-the-box we should give people a concept of 'microsites' and staging.  I have written about this numerous times about using accessrules to apply retail views using portal_skins.changeSkin method.   Not only does this need to be documented it needs to be considered best practices.

Users of a public web site should never -- never -- be presented with a way to log into the CMS.

Since users dont have a understanding of the above changeSkin using accessrule.  They think that Plone is *required* to act this way. 

Stop it with the jargon already.

We are getting better about this

Why do you insist Web sites have "columns"?

This was because he didnt understand that you could change the skin to a retail view. 

You will notice that if we would explain this 'applying retail views using hostnames to differentiate admin from public' we would have solved most of this guys complaints.  Education is very important.  In fact it is what is keeping Plone from widespread adoption.  It is not a technology problem.  It is creating quality mateirals, presenting the mateirals and people being able to discover the materials.

So here is my reply to this guy but since I dont read/use weblogs much.  His weblog system asked for me to comment but when I tried to post it said his weblog was not accepting comments (why did it allow me to reply to this weblog?).  I think he was using something called movable type which is regarded to be on the best weblog systems around.  Then why does it have such a obvious usability problem? *smirk*

My response which was rejected because Comments are not allowed on this entry.

If the biggest problem you have with a CMS is 3 column layout -- either your not looking hard enough or your requirements are rather shallow.  I do agree that the state of CMS is rather sad.

Your problem with Plone, is that you do not understand how to apply a different view to your website.  You were trying to customize the Plone administrative interface.:

  - You should not try to customize the plone admin interface.  It simple to create a folder off the root of your Plone called, say, public_website. 

  - Create a skin using Zope PageTemplates (this could be hard for you as well - not sure if you like ZPT). You have to read up on how to create a skin.  Then register it as say "RetailView".

  - Create a AccessRule in your public_website that when you go into that folder and the URL is a retail url such as <a href="http://mysite.com/">http://mysite.com/</a> that it applies the RetailView.


  - Finally set your virtual host to point mysite.com to the public_website and set admin.mysite.com to point to Plone.  voila.

I think its very difficult to support all the aspects of site building in one application.  For instance, it will be difficult for other systems to handle the translation functionality that LinguaPlone gives you with Plone. Then add EnSimpleStaging which gives you a simple versioning and Staging solution, ouf-of-the-box.

In my world its not about if something is called mambots or if it has 3 columns.  I need to be able to make sophisticated websites that fulfill business rules and can be customized quickly, easily and maintain robustness.   In my experience Plone seems to accomplish this very well although it requires understanding of the system (just like it would require you to understand best practices of interwoven or vignette).

Its not what Plone can do for you

Plone is the livelihood for tens of companies supporting an estimated revenue of approximate 100 million dollars globally.  What are the companies doing?  Why are they not helping with documentation?  Task-oriented documentation would be fantastic contribution to the Plone community in which we could all use to pass to our clients -- if it was quality.  I will save the 'what others are contributing' rant for another time.  But I would like for the community to reach and help work on a area of Plone that is sorely lacking.  Documentation.  Specifically Task-Oriented documentation. 

Documentation that clearly states: Here is the problem, Pre-requisites, Tasks, Post-instructions, Conclusion.  This way people can easily look up specific problems and solve them in a uniform manner. 

The amount of documentation is not the problem (there are 4 books and countless articles, blog entries, online tutorials) its a systematic way of introducing people into concept of Plone and making it better.  We need someone who has endurance and can overhaul our documentation story to the public for Plone.


Hmmm.

Posted by wsfulmer at December 05, 2005 - 23:55

Veen's website has a right-hand column, chock-ful-o portletish things. Go figure.

Documentation

Posted by Aaron VanDerlip at December 06, 2005 - 23:10

Veen's column made the rounds last year, and my impression reading it then was that he did a 30 minute review of each system to come to his conclusions.

People always complain about the state of software and for good reason. Frankly there is a lot of bad software out there. Projects like Plone are works in progress. The first releases of Mozilla were pretty rough even though they were better than the version of Netscape that was around at the same time. Mozilla became the base of Firefox, a browsers that in my opinon does not suck. Plone is on this same trajectory, it is getting better. We all bitch about, but not because we are stuck with how it is, but that we want to make it better.

I think Veen is flat wrong in lumping Plone in with CMS tools that misunderstand their audience, but perhaps the audience he deals with is a world away from mine. I have had nothing but success deploying Plone sites to small non-profit (low tech, low budget) organizations with widely varying degrees of technical skill. Almost everyone gets it within a few hours. Orgs that once struggled with their web presence have become empowered users. Plone developers understand their end users by making the tool easy and consistent to use.

Task-oriented Documentation.

As I am involved in developing end user docs for my clients, and hope to release some of these to a project that is larger in scope, I would be interested in seeing and example of what you had in mind as far as task-oriented docs. In fact, the best practice you mentioned in your entry is one that I have been wishing someone would write so that I understand the benefits. The best practices around structuring the back end of Plone using access rules, is something that is only mentioned in brief on the lists, so I am reluctant to implement it without knowing the how and why.

Seeking howtos from info in this article

Posted by Jeremy Hoff at December 10, 2005 - 17:31
Greetings, and thanks for the great article. You touch on something that I'd like to learn
specifically the part where...

" - You should not try to customize the plone admin interface. It simple to create a folder off the root of your Plone called, say, public_website. - Create a skin using Zope PageTemplates (this could be hard for you as well - not sure if you like ZPT). You have to read up on how to create a skin. Then register it as say "RetailView". - Create a AccessRule in your public_website that when you go into that folder and the URL is a retail url such as http://mysite.com/ that it applies the RetailView. "

Where do I "register" this ZPT as "RetailView"? Or is the word register simply another way to describe give it the name....?

How do I best control where new content is created? For example, if I set this folder with the public_view of my website, then the content itself may reside outside of the folder. I don't want links to news_items to appear as though they came from another site... etc... I prefer news_items to appear as though they are in http:///news.

Obviously I'm missing something here. I appreciate any direction. :-)

-jeremy

Task-based Documentation

Posted by Chris Calloway at December 21, 2005 - 15:09

I believe this "task-based documentation" is a clue. It assumes there are use cases for commonly expected CMS tasks which Plone solves. That is, suppose we enumerate and elaborate the use cases which are "critical for Plone to take over commercial markets." How many would Plone solve? Many, I'm sure.


Powered by Plone CMS, the Open Source Content Management System

This site conforms to the following standards: