We are continually working on improving the Zwiki documentation and bringing a more polished end-user orientation to zwiki.org. Here we discuss this process. To read Zwiki documentation, start at FrontPage.

Zwiki is a documentation/discussion/bugtracking tool being used to document/discuss/bugtrack itself; tool and documentation are co-evolving.


These include:

1. reduce the need for documentation (cf ZwikiPrinciples). Documenting the software as it stands today should help us see how to make it simpler and smarter over time.

  1. keep the large zwiki.org wiki clean and effective (WikiCleanup)
  2. pursue an optimally clear, useful, effective FrontPage
  3. use a book metaphor (eg) to organize all the Zwiki-related content on zwiki.org (UsersGuide, AdministratorNotes, DeveloperNotes)
  4. develop a clear, focussed quick help page to be available in all zwikis (HelpPage); how does this tie in with the previous ?
  5. ditto for other default pages in newly-created zwikis (DefaultWikiTemplates)
  6. docs translation (eg TranslatedPages)
  7. develop new "guides":#guides based on the organization below (UsersGuide, AdministratorsGuide, NewDevelopersGuide?)

Proposed new organization of Zwiki docs

  • user, admin, dev guides to be the center of zwiki docs. User & task-centric.
  • few, long chapters, without many subtopics (?)
  • pages follow a standard pattern, eg: toc, big picture, essentials, details, questions & answers, recap, next steps, sources, comments
  • docs include examples, sample real-world problems, screenshots, pictures, quotes. See also ZopeWiki:ZopeWikiPolicies
  • Faqs to be integrated on or under every page, or at least within each guide.
  • Howtos included in each guide, at the end.
  • Issue categories follow major guide sections.
  • Major sections display doc completion status (%), bug count, and implementation quality status (alpha/beta/production).
  • Guides are concise, powerpoint & picture style; excess notes & docs are parented elsewhere.

Docs should keep in mind the following imaginary readers

  • Ulysses User -- Ulysses uses one or more zwiki sites. He wants to get things done; he doesn't want to know about Zwiki, most days. He might or might not research or report bugs.

  • Adam Admin --

    Adam runs one or more zwiki sites. He has ZMI access in the wiki folder and in the Plone site folder, if any. He may or may not have installed Zwiki himself, and may or may not have the ability to upgrade or patch the product. He may or may not be able to use darcs. He might research or report bugs, and can be expected to do so after a bit of encouragement.

  • Deborah Developer --

    Deborah can restart zope and change the Zwiki product at will. She develops or contributes changes for the Zwiki product code, plugins, or skins, or she develops other zope products. She can be expected to research or report bugs and to use darcs.

Open issues

New Guides

  • do one guide/section at a time
  • follow template described above
  • begin by linking all likely sources
  • gather relevant existing content
  • flesh out, rewrite
  • update completion status

<a name="guides" /> <table> <tr valign="top"> <td>

<h3>UsersGuide <span class="seventypercent">(70%&nbsp;complete)</span> </h3>

for Ulysses User

  • monitor a wiki
  • find things
  • avoid posting junk
  • archive discussion
  • make a faq
  • make a blog
  • document a project
  • keep a wiki organized
  • research and report bugs

</td> <td>

<h3>AdministratorsGuide <span class="seventypercent">(70%&nbsp;complete)</span> </h3>

for Adam Admin

  • get a zwiki of your own
  • set up a private wiki
  • set up a public wiki
  • set up member registration
  • limit page types
  • show and hide features
  • change colours
  • move things around
  • run in plone
  • set up wysiwyg editing
  • set up a non-english wiki

</td> <td>

<h3>DevelopersGuide? <span class="twentypercent">(20%&nbsp;complete)</span> </h3>

for Deborah Developer

  • [introduction to the project]?
  • history, timeline, roadmap
  • license, copyright
  • discussion & documentation
  • darcs
  • monthly releases
  • how to help
    • wiki gardeners
    • support & training
    • testers & bug hunters
    • python developers
    • skin developers & designers
    • translators
    • writers
    • artists
    • system administrators
    • funders
  • [functional overview of zwiki]?
  • browsing
  • editing
  • page types
  • page hierarchy
  • mail
  • issue tracking
  • page rating
  • dtml scripting
  • fit tests
  • purple numbers
  • installation/upgrade support
  • skin support
  • i18n support
  • get the latest code
  • test zwiki
  • report a bug
  • clarify bugs
  • write a test
  • contribute a patch
  • improve the documentation
  • add or update a translation
  • make a donation
  • fund a specific task
  • clean up the wiki
  • contribute a diagram or logo

</td> </tr> </table>

See also: