Note : "FeatureX" stand for "any feature" (or what concerns all features).
Let's take an example of ))FeatureX(( and illustrate how we could organize its documentation. FeatureX could be Blogs, DBabstraction or any other of the 40-50 major features. A list of major features is kept at TikiFeatures.
All information related to FeatureX should be included in:
- FeatureXGloss - short glossary definition, for everyone
- Using the
INCLUDE Wiki tag, this blurb can be quickly inserted into any or all of the following ))FeatureX(( pages.
- See the Wiki syntax of Directory for an example.
- {INCLUDE(page=>DirectoryGloss)}{INCLUDE}
- FeatureX - general info, for everyone
- FeatureXDoc - what FeatureX does NOW, for users
- FeatureXDev - what FeatureX will do LATER, for developers
- FeatureXAdmin - how to configure FeatureX, for all site admins
- FeatureXSettings - site-wide configurations, for the head TikiAdmin and/or SysAdmin, when applicable
- Mainly, these are the settings made from TikiAdminSettings.
Please do not create a page if it doesn't apply. Specifically, do not create a FeatureXDoc page for an admin-only feature. Please add the info to FeatureXAdmin instead.
Ex.:
- DirectoryGloss
- Directory
- DirectoryDoc
- DirectoryDev
- DirectoryAdmin
- DirectorySettings
Or:
- DbAbstraction
- DbAbstractionDev
- DbAbstractionAdmin
We will use the HotWord feature to automagically link to the feature when it has only one word.
We could have different templates for the each. ex.: feature is Blue, Doc is Green, Dev is Red, Admin is Yellow, etc
These pages are consistently linked together. It has to be very easy to go from one to the next. There are content templates for Feature, FeatureDoc, FeatureDev, FeatureAdmin to help everyone be consistent.
We should try to keep the dev mailing list & general forums for things which are not covered by these "FeatureX" forums.
Each wiki pages is subdivided in section. Clever use of the new expand/collapse feature is a good idea.
FeatureX wiki page
[+]
To create a ))FeatureX(( page, do the following:
- Please read DocConventions! You'll find lots of useful tips for writing great user documentation.
- Create a ))FeatureXGlosspage that defines the feature in simple, clear language. For examples, see ((FaqGloss and WikiSyntaxGloss.
- Now create a ))FeatureX(( page.
- Click Apply Template, and choose the Feature template.
- Click Show Categories.
- Ctrl-click Documentation, Documentation::EndUser, Feature, and any categories under Feature that apply to the feature you are documenting.
- Under the title at the top of the page, insert an INCLUDE plugin command that incorporates the ))FeatureXGloss(( you created. Here's an example: {INCLUDE(page=>FeatureXGloss)}{INCLUDE}
- Add a Quick Reference section that will appear under the glossary text. For an example, see WikiList.
- Below the quick reference, add a link to the ))FeatureXDoc(( page.
- In the Key Function and Sub-Features list, try to list everything the feature can do.
- In the Related Links section, add links to this feature's Doc, Admin, and Settings pages.
- In the Typical Uses area, explain why the user would want to use this feature.
- Add additional information, if it's available, including a link (made with SourceForge trackers plugin) to all featurex valid trackers for the latest stable version. This means RFEs and bugs, including closed ones.
FeatureXDoc wiki page (what featureX does NOW)
[+]
-Please see: OldTikiWikiDocumentationPlan
-Has the documentation with screenshots (what we currently have in PDF/wikified by Scott).
-Has links to the live featureX on tiki.org (when appropriate)
-This page is kept nice & clean as it will be used for the Docs
-This doc section is for the official/Release candidate version. (not stuff in CVS)
-Knowledgebase / learn / FAQ / How-to
-Documentation is focused toward end users and power-users. (but not devs) Please see DocConventions for guidelines.
-This information will be used with wiki structures to export to different formats (Official PDF docs, docbook?, one big html file etc). Ideally, someone could generate a custom-printable-manual which covers only the 3-6 features which he/she uses.
-Placed in appropriate categories.
FeatureXDev wiki page (what featureX will do LATER)
[-]
Here is a proposal for a typical page of a complex feature. Some features may not warrant as much detail.
Status/RoadMap
[+]
Where are we? Where do we want to be? Who is working on what? (Priorities/goals/majors issues/roles)
When a new sub-feature is added, the roadmap is updated (in addition to changelog.txt). When there is a major breakthrough, the devs should post an article on the tiki.org front page. In the short term, a wiki page will be OK. In the future, this could be improved to be using workflow/trackers/todo list. Some developers may want to use a blog te report on their progress. We would tag all Roadmap items with version numbers so we could easily have a master/global roadmap.
We can look at the example from the fine people at Xaraya:
http://docs.xaraya.com/docs/roadmap.php
Team
[+]
Has the list of team members (with hyperlinks to their userpage). Team members are expected to subscribe and monitor all three pages and the dev forum. Using the backlinks from a userpage will show you all the stuff he/she is working on
Trackers
[+]
Hyperlinks to appropriate trackers on SF (Bugs, RFEs, tech support and patches). Let's add Dennis Daniels creative hyperlink to SF bugs and RFEs. Dave Sanders has done excellent work on categories on our SF trackers.
-Hard Link to open "featureX" bugs (SF trackers) for CVS version
-Hard link to open "featureX" RFEs (SF trackers)
It would be nice if these hard links were RSS feeds instead. So you could have all the info on the page, without the extra clicks.
We expect team members to follow up on these trackers. When bugs are solved: It is very important to indicate in which branch. So users know to what version they need to upgrade to solve a bug. This could be in the canned responses.
Competition and standards
[+]
List of other products with similar/interesting/related features. Here I would like to see some "editorial" content. How do our features compare to others? This will let Tiki Evaluators know if the features they need are good enough for them. The Beat PHPBB project comes to mind.
Also, linking to several competitors in a field has an interesting side effect. We can get some traffic from people looking to compare some well know competitors. Ex.: Someone is looking for a comparison of vbulletin, phpBB and Phorum.
This may lead also in the future to some partnerships and/or increased userbase. For example, if a smaller project is going to stop development, we could work with the authors on a data migration script. At least users of the old project will have somewhere to turn to.
CVS Doc section
[+]
This is where new features (only in CVS) are documented. When the CVS becomes RC/official release, the info in the CVS docs is transferred to update the official docs (FeatureXDoc).
Any documentation for featureX which is targeted to developers and not end-users can always be kept here. If the dev documentation is comments in the code (or anywhere else), then it should be indicated here.
There could be a link to the viewCVS directory where the code is.
Discussion/participation
[+]
A forum from this page brings users to a place where ideas can be exchanged, debated, etc. Interested people can subscribe to the wiki page and/or to these forums as they would a mailing list. Once a conclusion is reached, the roadmap is updated. Discussion (forum) -> RoadMap (Wiki)
We need the info well organized, well categorized and easily searchable. IMHO, Threaded forums where titles are updated are the best.
The dev team may opt to add a poll or survey to ask people what future sub-features they would prefer. Ex.: for the calendar, do you prefer iCal or SyncML support?