home contents changes options help subscribe edit (external edit)

last edited 6 years ago

Ok, let's start at the discussion. First thoughts and just brainstorming

Tom

Firstly what are we going to orginize? We've the following:

  • The O'Reilly Zope Book
  • The Zope Developers Guide
  • Document Template Markup Language Reference
  • Zope Administrator's Guide
  • Zope Content Manager's Guide
  • Zope Developer's Guide
  • Z SQL Methods User's Guide
  • Zope Quick Reference
  • How-To's
  • Tips
  • Chats
  • Up-to-date? Source Documentation (http://www.zope.org/Documentation/Developer/ZopeSrcDocs)
  • We should also put in links to the beehive docs (and any other 3rd party docs) where appropriate - mindlace

Added 03/10/2000 Rik Hoekstra

  • Wikis
  • Miscellaneous bits of documentation on the ZDP site and in member pages. There is also the FAQ and the Snippets on ZDP
  • Interface documents
  • Zope Help system (do we need to address this, how?)

New?

These are the following tasks we're facing at?

  • Provide a user friendly and fast (ie easy to find information) documentation web page

    mindlace 04/10 This is the top priority, yes.

  • Provide a way to store all this information, so that lookup and search is easy and direct?

    mindlace 04/10 I'm not sure what this means, but we're not making any tools this time around.

    tom 05/10 is te same as point 1.

  • Provide a way to allow an easy way to add comments to the documentation?

    *Rik Hoekstra 03/10: Nah, no public comments please

    mindlace 04/10 We'll do this systematically in the next version of zope.org. Not in the works now.

    tom 05/10 I think some comments can be helpfull for improving the documentation. (If good tools are available, cfr. my post on ZWiki? Wiki)

  • Provide a way to easy add documents in the documentation-portal. So that the doc finds automatically its place.

  • Provide means to present the documentation (over all categories the same interface) : printer, download, ...

    mindlace 04/10 not a bad idea

  • ...

How to get started?

  • We've to put the documentation into groups which will be handled the same. eg. A guide and a book can be placed in the

same category. But a FAQ or How-To is different as a guide or a book.

  • Paul suggests role oriented grouping. What I think is that we have topic oriented grouping, and then role oriented grouping. I don't think that content-type grouping is very meaningful. I never think "I'm looking for a Tip/Guide/HowTo?" I think "How do I solve this problem" mindlace 04/10

tom 05/10 Yes, better idea, but it would also be nice to have every document fixed to a certain categorie. Every categorie has straight guidelines to follow. Depending on which guidelines you follow will eventually typecast your document to a certain category.

So which groups to we have?

  • Guides and books
  • How-To's, Tips and FAQ
  • Code Snippets (?) added 03/10 by Rik
  • mindlace would say "developer, buisness, site builder*. Then we make the developer stuff link straight from dev, and the other stuff will link to

their respective areas when they get developed.

Tom 05/10 Mmm, problem sometimes is that people don't know in which group they belong (like me), or to which place the information will be meaningfull. What is the difference in a Zope developer and Zope Site Builder? Some Products need to be developed for making a site and thus a site builder will work on a product. What with information which overlaps some of the groups?

  • Parallel to this organization, there's also topics, like server, dtml, etc. I was hoping that Tim Cook's categorization of the how-tos would help here. EG:

    • deploying Zope & Apache
    • A comparison of Zope and other app servers
    • Using Zope & Pike in Roxen

    These three things are all "server" documentation, but they're for each audience.

dev/currentprojects dev/proposed projects dev/zopecore dev/projects dev/projects/ptk

build/api build/products build/products/ptk



subject:
  ( 1 subscriber )