Join the mailing list!

https://lists.sourceforge.net/lists/listinfo/plone-docs

 This is some historical info on our conversations up to the point of Spring 2007. Keeping it here for posterity.

 

 

 

 

Introduction

When running into problems with Plone or starting off as a newbie finding a piece of documentation on plone.org or with Google can be a pain in the bum. Documents seem scattered, ill-structured, incomplete and sometimes contradictory. To improve Plone's documentation this project was started by the documentation team. There is an "internal" part of this project in the documentation team's wiki (non-public) and this "external" part for collecting the input of documentation readers. So this is where the public discussion is going on and when things have been agreed on by the documentation team they will get transfered to the internal wiki.

Please use this chance to help improve Plone's docmentation, for many people the lack of quality of the current documentation is what prevents Plone from being THE coolest CMS out there. Let's change that!

The project is split up into several phases:

• Spot the problems:
  To be able to improve things we must first know where the problems are, so everybody who feels s/he has something to say about Plone's documentation (or lack thereof) is invited to add items to the sections "Shortcomings of the Documentation Area" and "Possible Roots of the Identified Problems". Make sure to read the introductions of those sections to distinguish between the two.
  
• Collect ideas:
  After spotting the problems we will open a section to collect ideas on how to solve those problems. These ideas should not be restricted by current technical limits of the Plone Help Center but show up an "ideal" that we can aim for. To keep things separated and force people to concentrate on one thing rather than rant uncontrollably this section will be opened only after the first phase has been completed.
  
• Filter, categorize and order ideas:
  In this phase the collection of ideas will be evaluated and ordered by priority and ease of realization. Again, this phase will be opened only after most of the previous phase has been completed.
• Implementation of ideas:
  This is where we will actually start to work on the realization of the acquired solutions. This will start only after the other phases have been completed.

Shortcomings of the Documentation Area

Deadline: Wednesday 17 January 2007, 20.00 GMT (1)

To be able to improve the Documentation Area we need to set up a list of the problems that persist. From those we can discuss new ideas to enhance it. Please put down the "symptoms" of problems that you have spotted here and use the next section to investigate on the cause of the problem. Also edit existing items when you feel that they don't cover everything.

• Redundancy:
  Many documents have passages that overlap with those of other documents. While this irritates the reader only slightly it is difficult for the editors who need to update documents when the covered subject is approached differently.
• Inconsistency:
  With the redundancy also comes inconsistency. Document A tells you to do one to address a certain problem while Document B tells you to do something completely different. This is very frustrating for the reader who does probably not know what the advantages of one approach or what the best practices would be.
• No sequencing:
  The documentation is scattered which sometimes makes it difficult to find what one is looking for. Even worse is the fact that readers can not follow a given set of documents on a given subject that turns total beginners step-by-step into experts.
  Having a straight forward start to finish format could work nicely. These could be done in modules or could be focused on level of participation, expertise and such.
  
• Lack of integrity:
  There are some small and also some big holes in the documentation. Some subjects are completely missing, others don't get covered in detail.
• Bad structure:
  Some pieces of documentation are badly structured and can not be followed easily because they seem to go back and forth all the time. Sometimes the learning curve starts off rather flatly but gets very steep all of a sudden.
  
• Obsoletion:
  Some documentation is obsolete or specific to a different version than the user might be looking for.
• Poor organization:
  Documents are primarily organized by document type (how-to, FAQ, tutorial, etc.) rather than by task or audience, which makes it more difficult to find related documentation. Within the audience classification, tasks or topics are poorly chosen (for example, End users includes a "Installation and Setup" section). (2)(3)(5)
  
• Confusing classification of audience type:
  The classification of who the articles are intended for are a bit confusing.
• Just one learning style addressed:
  There is little use of images and videos.
• Search Considerations:
  The Search function is a bit difficult to follow and does not always point towards articles or tutorials that the user intends to be reading about. Greater consideration into the type of key words used to tag these articles can be considered. There is certainly need for tech-savvy terms to be used but there is even a greater need for less tech savvy terms to be used as key words.
• Documentation on making Plone work with LDAP was not stunning in 2.1, but was usable. For 2.5, LDAP /PlonePAS , there's a real lack of documentation, and on the newsgroups many people ask questions and don't get answers.
• Doesn't reference outside sources:
  There are books, books online, articles, screencams, and even product guides which are part of the definitive Plone documentation, but aren't referenced by audience/topic from the Plone documentation section.
• Documentation isn't always generalisable:
  Sometimes very useful documentation (e.g. setting up LDAP) is written for a very specific combination of Zope/Plone/platform/use case. This makes it difficult to re-use the knowledge in a related but non-identical setting.
  

Possible Roots of the Identified Problems

Deadline: Sunday 21 January 2007, 20.00 GMT

This is where you should try to analyze where the problems come from. The items in this list do have not correlate directly to the items in the last section since some problems we spot here can cause a combination of symptoms in the list above.

• Missing outline:
  So far there is no "big plan" that clearly states what subjects should be covered by documentation.
• Missing collection of "best practices":
  Redundancies and inconsistencies could be avoided if there was a collection of best practices for the most basic and most important tasks in Plone. This can include end user issues (somewhat covered in the Plone End User Manual) or developer tasks (like what's the "right" way to get the content of a folder).
  
• Lacking guidelines for writing and reviewing documentation:
  There are no guidelines that take an author "by the hand" and guide him/her through the process of writing a document, tell him/her what to think about in advance, how to structure different types of documentation and how to make them at least somewhat visually appealing and interesting. Not everyone who is a genius when it comes to writing code is also a genius when writing documentation, guidelines would help in those cases. Reviewers would also benefit from stricter guidelines because it would make it easier to judge if a piece of documentation fits the needs or not.
• Tagging and categorization insufficient:
  It is not always clear what versions of a given product a piece of documentation is talking about and what exactly it covers. Sometimes one document tries to cover way too much ground which makes it even more difficult to quickly see what it's about and whom it's for.

Collecting Ideas for Improvement

Deadline: Sunday 28 February 2007, 20.00 GMT

Here we are going to collect the ideas we had concerning the documentation area. Please try to create/modify subheadings where appropriate, one long list might prove difficult to manage.

• Break up Documents according to Subjects: To increase the maintainability of documents existing pieces of documentation should be broken up into small chunks that focus on one subject. When these chunks are properly structured in themselves and adhere to the same guidelines, it should be possible to consolidate the information about one subject in different documents and re-use them in different learning trails. Like that, there would be one concise statement on how to achieve something, and not small pieces of the whole picture in different documents that may even give contradictory information. Since very small chunks might feel very disrupting to the reader great care must be taken to find a sensible size.
• Establish an outline for documentation: To be able to get an overview of holes in the subjects covered by already existing documents there should be a "major plan" that outlines the subjects that documentation should exist for. This outline must be very structured by subjects and sub-subjects.

1. See this Map

• Organize Documents in Learning Trails: If the documentation chunks are well-structured and adhere to a common layout and language, it would be possible to put them into learning trails that cover bigger-scheme problems. One chunk could be used in many trails and thereby easily be kept up-to-date.
• Establish Guidelines for Documentation: A piece of documentation needs a certain structure that makes it easy for readers to follow the text. This is true for all documentation (eventhough different types of documentation might need slightly different structures) but becomes even more important when different pieces of documentation should be "linked" together in a learning trail or book-like manner.
• Adressing Different Learning Styles:
  Screen casts are always nice, and pictures too! Remember there are many kinds of learning styles out there and they should all be addressed. Perhaps someone with a sweet (or handsome) voice can get on board with this and create some simple oral walk-throughs and screencasts.
• Better Organization of Documents:
  here should be some sort of clearer rating system to direct the users toward articles that are suited for their level of expertise. There should also be a link or pointer to articles that go a bit more into depth on the subject that is being read about. Perhaps a 'tree' construct that expands as more detail is needed.
  

Discussion

To keep the list of problems, ideas and solutions clean please use this section to discuss things. Add your nickname and your comment as a new list item. For comments on specific sections in the text use the "Annotations" below.

• DaftDog: The next step will be collecting ideas on how to improve Plone documentation. Discussion on this will open on Sunday 14 January at 20.00 GMT when the collection of shortcomings will be completed, so check back then and add your ideas when you have them!
• anneb: I think the documentation has really improved over the last couple of years and I'm very grateful for all the help I've received from it. If there was one aspect I'd like to see prioritised , it is organisation. I don't find the existing documentation particularly badly written, I'd just like to be able to find it!
  
• DaftDog: Ok I see the structure I intended with different deadlines doesn't really work very well, I will open the "Ideas" section soon so people can put things in there. The deadlines will remain the same though, so we'll close one phase after the other, keep those problems coming until then!
  

Annotations

Here you can add annotations to specific parts of the text, just add a list item below and insert it's number in braces into the appropriate section in the text.

1. I have changed this deadline to be able to collect more input from users.
2. The task categories are far too vague - things like 'Make New Content Type' or 'Change the Navigation Tree' would be more accessible.
3. Can we add presentation to this list - scrolling down a single page of repeated titles makes it hard to find things and even harder to come back to the same item.
4. There's an added confusion with product documentation embedded in products - it is sometimes difficult to remember where to go to find the information you need.
5. A proposal to clean up the End Users portion of the How-to main page sooner rather than later.
   

Please enter some text for your page