Loading...
 

OldTikiWikiDocumentationPlan

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

[+]

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

[+]

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. neutral

Actions/Next Steps

[+]

Further Information

  • For a list of Tiki features, with their Glossary entries:
    • TikiFeatures
  • For an explanation of the various Wiki pages needed for each feature (i.e., FeatureX, FeatureXDoc, FeatureXDev, FeatureXAdmin):
    • FeatureX
  • For a list of Wiki feature pages that have been written or are currrently being written and a proposed process for editing them:
    • FeatureReference
  • 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
Created by: Last Modification: Friday 20 September 2019 15:57:09 GMT-0000 by drsassafras
List Slides