Note this is a work in progress and I am trying to capture all the
great ideas that everyone has contributed to the list over the past three or so months. I've stolen many of the ideas and details from others and hope we can make this usable for everyone. This page will be volatile over the next week or so.
-swf 7 July 2003
Goal
To be able to produce the Tiki 1.7 (and later) release documentation in an easily maintainable and distributable fashion. Other parts of this goal include:
- Maintain documentation source in native Tiki format as the ultimate TikiWikiCaseStudy
- Ability to produce normal output formats (list to be determined: PDF, Word, etc)
- Easy for each class of users (developers, site administrators, end-users, etc) find only what they need
- Easy for developers to create documentation that maintains consistency in both content and format
- Easy for site administrators/content managers to develop local-site documentation and still be able to upgrade with new Tiki releases
Requirements
[+]
- Must allow for professional quality documentation, including graphics, charts, code snippets and other objects
- We want the Wiki doc to updatable between versions and the ability for the site operator to annotate those docs we must be sure that we don't step on those local changes.
- Different versions of the documentation should be developed for the following audiences, each of which has its own, unique needs
- Each topic (for example, hotwords) should be introduced with a brief conceptual overview, a tutorial, a comprehensive how-to section that documents all relevant capabilities, a "where do I go from here" section, and (where appropriate) a reference section.
- All documentation should be accessible from two perspectives:
- How do I use THIS FEATURE?
- How do I perform THIS ACTION?
- All documentation must meet accessibility guidelines (which the editor will need to specify)
- All documentation must be readable at a 10th grade level.
- All new pages are added to the hotword list so that it is always linked throughout the wiki. (Suggested new features: Automagically add new Wiki page names to a new version of the hotword list, called Index. This should be presented attractively, with pagination and a search box.)
- All new pages are incorporated into the wiki structure in an appropriate category (or a new category is created).
- All terms and concepts are defined in a separate glossary page; page is hotworded.
- Each page is categorized according to subject descriptors developed by the author and editor.
Types of Users
[+]
Evaluators of TikiWiki
Need to see:
- what features does TikiWiki provide
- what requirements are needed to run/install TikiWiki
- case studies - how is TikiWiki being used by other sites?
End users
Need a GettingStartedGuide
Site Administrators
Power users
Content Managers
Developers
Tiki
Site Customization/plugins
Partner integrators
Templates
Documents to be produced
[+]
Marketing
ReleaseManual (brain is fried and I can't think of the correct title)
InstallationGuide
GettingStartedGuide
SiteAdministratorsGuide
ContentAdministratorsGuide
TemplateDevelopersGuide
FeatureReferenceManual
DevelopersGettingStartedGuide
SiteCustomizationGuide
Adding local plugins
Creating site specific documentation
Customizing site look-and-feel including theme developent
Components
[+]
Wiki pages
Output utilities
Input utilities
Content standards
Distribution of native format
Distribution of output formats
Status/tracking of documentation
Roles
[+]
Release manager
What Bryan Pfaffenberger referred to as:
Coordinator - NOT the author, unless you wish to invite disaster. Keeps an eye on the whole the process to make sure it happens, recruits translators, admonishes the wicked, praises the virtuous, keeps the site running, etc. Should be someone from the lead development team.
This is the task master, someone willing to assign and track/report status. Watches the changelog like a hawk.
Standardization
What Bryan Pfaffenberger referred to as:
Designer - creates templates, ensures conformity to accessibility guidelines, makes sure there is a consistent look, etc.
A good technical component to this would be the content templates proposal
from Chris Kaleiki (anenga).
Feature developers
For all 375+ features, maintains a list of what a given feature does, what it doesn't do, what it might do someday, and (if not obvious) how to use it. When upgrades occur, adds and highlights new features. (This can and should be expanded to include tips for developers.)
Non-technical developers
This is really, I think, the most valuable set of contributors to documentation quality. Here is where we make the documentation really useful for end users and content managers. This is where I expect many of the case studies and examples/howtos of how to use the different features of Tiki together are going to come from. Also included in this would be the marketing aspect.
Editors
Checks to make sure documentation meets criteria and is complete; examines and approves/rolls back changes to wiki pages, examines and approves/deletes reader comments (like those appended to the MySQL documentation)
Utility developers
A sub-group of Tiki developers developing utilities related to documentation. This includes things like:
- PDF generation
- Wiki structure based output
Translators
I gotta mention them here, but I really don't want to have to think about this right now. I can only think in one language at a time. 😐
Actions/Next Steps
[+]
- 1.7 Release Documentation
- Migrate Tiki-format documentation from demo (and other) sites - complete 7 July 2003
- Rename pages to Marc's naming standards - complete 7 July 2003
- Verify Doc and Dev pages have all the right sections
- Identify missing pages/mis-used pages and start fixing (e.g. Dev paragraphs in the Doc page)
- Insert tables for feature permissions where insert graphic has a placeholder
- more
- Fix HTML rendering bug
- Figure out way to include images and other objects
- Figure out way to keep different versions of document structures
- Identify what documents need to be produced
- Develop Case Study format
- Develop Tutorial format
- Create Content Templates for Feature, FeatureDoc, FeatureDev and FeatureAdmin to ease creation and ensure consistency