This page is to brainstorm and document what has been done in Tiki in the way of automation its documentation. This is beneficial because it keeps Tiki specs up to date with the online documentation. It also often means that efforts to document only need to be done once, instead of within the wiki code and also within the online docs.
Ideal Solution Features
- Provide Tiki version history of evolving specs
- Have formatting available for a rich experience online.
- Is 100% self-updating, requiring no human intervention
- Provides a solution to a wide array of documentation needs
- Provide a standard user experience
- Has a low barrier of entry for updating documentation
Dream Features (may not happen but would be nice in a perfect world)
- Can generically pull documentation from a wide array of places, such as outside of tiki etc.
- Documentation could be updated both in code and online
Currently Automated documentation:
- Tiki preferences through PrefDoc Plugin
- plugin list with Plugin Manager
- plugin details with Plugin Manager
Documentation pages we should automate:
- Database Access - Many aspects here might get out of date and have differing version requirements.
- Tracker Field Types
- Fields and their variations available in the search index as seen Unified Index (always out of date)
(Should be taken from objects implementing\Search_ContentSource_Interface::getDocument
orZ\Tracker_Field_Indexable::getDocumentPart
and should be double checked with\Tracker_Field_Indexable::getProvidedFields
,\Search_GlobalSource_Interface::getProvidedFields
and\Search_ContentSource_Interface::getProvidedFields
perhaps) - All Preferences
- All Plugins
- All Modules
If we had a solution that could create documentation from diverse sources, other software projects could use tiki to solve the issues they also have in in-line documentation vs online documentation. Might bring much welcome attention to tiki form other software projects.
Also of note is that Plugin Manager does not retain version history, and there are inconsistencies between the interface that prefdoc and plugin manager produce, namely that the icons and formatting that are a nice touch in prefdoc are not implemented in plugin manager. Plugin manager also uses bolded lettering for defaults, while they appear in a separate column in prefdoc.
It is interesting to note that the All Preferences page looks significantly different than the All Plugins and All Modules page. Some discussion about what the use of these pages are and what kind of info should be shown is perhaps needed. There is currently a way to list all the plugins in a style more in keeping with how the plugins are displayed (name and description) in an automated way with Plugin Manager, but it seems like it is not utilized.