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.
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 MyTikiDoc for an example.
- {INCLUDE(page=>MyTikiGloss)}{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.:
- Blog
- BlogDoc
- BlogDev
- BlogAdmin
- BlogSettings
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. We could use the content template feature 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
[+]
- Please see FeatureReference
-A summary/general information about the featureX.
-It includes the marketing hype, list of sub-features, etc
-"Related Links" to appropriate page (related features)
-All information which doesn't fit in Doc or Dev
-typical uses for featureX
-examples / case studies
-Placed in appropriate categories.
-Hard Coded Link to all (open or closed) "featureX" bugs (SF trackers) for latest stable version
-Hard Coded to all (open or closed) "featureX" support requests (SF trackers) for latest stable version
Example: I can check right away if there are any known bugs in forums for Tiki 1.6.1 (if they are solved, I can find out in which version).
FeatureXDoc wiki page (what featureX does NOW)
[+]
-Please see: TikiWikiDocumentationPlan
-Has the documentation with screenshots (what we currently have in PDF/wikified by Scott).
-Has links to the live featureX on tikiwiki.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)
-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 tikiwiki.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?
;){kind=link}
;){kind=link}