Outdated page
Note that this wasn't maintained since 20030824. Current effort is focused toward 1.8 documentation, more information is available on TikiDocumentation and on http://doc.tiki.org. Most information here is less pertinent than originally but some ideas are still true.
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
Note: I attached an archive that when extracted will produce a series of webpages providing
technical documentation for tikilib.php. This documentation was produced in 22 seconds using phpDocumentor, and can be updated anytime there is a change to tikilib.
The documentation would be greatly improved if there were inline comments in tikilib following the proper syntax Still, it's impressive. phpDocumentor supports multiple output formats from PDF to HTML and Windows Help files. I am hoping to get people familiar with the tools and syntax so that most developers can add the comments to their files, and anyone can run the phpDocumentor script on our sources. This is the favored approach in my opinion for generating the technical documentation for the project. Comments? There is more information on PhpDocumentor at the
phpDocumentor project website
- freephile 24 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 be updatable between versions and the ability for the site operator to annotate those docs we must be sure that we do not 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 doc:Requirements and Setup are needed to run/install Tikiwiki
- case studies (links to Case Studies category until I find a better link) - 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
[+]
Please see FeatureX for guidelines on the format of Wiki pages for specific features.
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,FeatureDevandFeatureAdmin(( to ease creation and ensure consistency - available as of 24 August 2003
Further Information
- For a list of Tiki features, with their Glossary entries:
- For an explanation of the various Wiki pages needed for each feature (i.e., FeatureX, FeatureXDoc, FeatureXDev, FeatureXAdmin):
- For a list of Wiki feature pages that have been written or are currrently being written and a proposed process for editing them:
- For a proposed set of conventions for documentation (when to italicize, when to boldface, etc.):
- DocConventions
- Also: Note the content templates available whenever editing a page:
- Feature
- FeatureAdmin
- FeatureDev
- FeatureDoc