Tiki Doc Content Reorg Proposal
pianoliv: This proposal from 2011 is still being worked on (2013), don't hesitate to join in!
Overview
The Problem
- The sheer volume of information/pages makes it difficult to find what you're looking for
- No clear standards of how to present the material
- Unable to produce print/PDF docs
- Multiple target audiences (Tiki admins vs. end-users (who may also be admins) vs. community members)
The Proposal
- Reorganize the content. Instead of single guide/structure, create multiple smaller guides.
- Make it easier for casual visitors to contribute/correct pages
1.1. Content reorg - Tiki Doc Suite
Instead of a single Tiki user guide (structure), a "suite" of Tiki docs was proposed:
Tiki Installation Guide
- Primary target: Tiki Admins
- Secondary target: Tiki Community
- Purpose: Install Tiki
- Organization: In logical order of tasks
- Online at: http://doc.tiki.org/Tiki+Installation+Guide
- Offline at:
Tiki Installation Guide.pdf ALPHA
- Completion: allmost done
- Notes:
- We have several old Upgrade X to Y pages. Not sure if they're still useful?
Maybe we could leave them out of the structure, but keep them alive (well, or don't delete them) for future reference.
pianoliv: I created an "archives folder" for such obsolete pages
- We have several old Upgrade X to Y pages. Not sure if they're still useful?
Tiki User Guide
- Primary target: End users
- Secondary target: Tiki Community, Tiki Admins
- Purpose: Perform a specific task, interacting with Tiki as an end-user
- Organization: Most common end-user tasks, grouped by Feature
- Online at: http://doc.tiki.org/Tiki+User+Guide
- Completion: allmost done (see this forum thread
Tiki Administrator Guide
- Primary target: Tiki Admins
- Secondary target: Tiki Community
- Organization: Most common Admin tasks, grouped by Feature
- Completion: allmost done (the tree is being built here)
Tiki Reference Guide
- Primary target: Tiki Admins, Tiki Community
- Secondary target: End-users
- Purpose: Screen-by-screen documentation all options/parameters for each feature/plugin/module/button/etc.
- Organization: According to the navigation in the application.
- Online at: http://doc.tiki.org/Tiki+Reference+Guide
- Offline at:
Tiki Installation Guide.pdf ALPHA
- Completion: allmost done
Other structures
pianoliv: I propose to create a couple of small structures for:
- Home
- Plugins
- Modules
- Tracker Fields
- Mods
- Archives
- Author Resources
See here for details.
1.2. Ease contribution
Documentation Categories
obsolete?
Currently, doc.t.o uses the following status categories:
Status
- 1.To Do (86)
- 2.Obsolete (13)
- 3.In Progress (229)
- 4.Pending Review (101)
- 5.Reviewed (4)
- 7.Validated (1)
- 8.Live (22)
I proposed a somewhat simplified (and perhaps easier) set of status markers:
- Stub
The page was created because it is needed. The template has been applied. But there is little or no content. - In Progress
Someone has started populating the necessary content. - Complete
Most (or all) of the information has been added. Page has been versioned, as needed. - Obsolete
The page/feature is no longer maintained (for example, Image Galleries) but the page remains.
pianoliv: agreed. I started migrating categories to status tags.
See this forum thread
Not sure if a "complete" tag is necessary. A complete page is one that doesn't have any other tags, as complete a page can be.
Also, I propose to not tag pages that are not in English.
English should be the reference (since not everyone can translate from all languagues), and localised pages are only a translation of this reference, thus have the same status. Localized pages don't need to appear in a status list.
One tag could eventualy be added in other languages, such as "Page à traduire" (page to translate).
Templates
By using standard page layout/design/templates:
- The pages will "look" as though they belong together
- Makes Tiki look more "professional"
- Easier to see what's missing
- More inviting for contributors (simply fill in the holes vs. "writing docs")
What should the pages look like? At a minimum:
Style:
- toc of the substructure
- local maketoc
- Numbered headings if long page (!!#, ...) to ease navigation wihin the page while scrolling up & down
Content:
- An image
- An example
- A table of parameters/options
- Would suggest using Plugin Manager for this as a default for plugins and modules:
Copy to clipboard{PLUGINMANAGER(plugin=addtocart) /}
The above code will produce a parameter table automatically for Plugin AddtoCart.
- Would suggest using Plugin Manager for this as a default for plugins and modules:
- How to arrive at the feature
- Links to related items
- Brief overview (what the page is for)
- Alias names for that page (either shown, or hidden from display with the tc (tiki comment) tag.
- ??
Sample
''Live sample here: http://doc.tiki.org/Security and http://doc.tiki.org/Spam+Protection
Copy to clipboard
! Page Name {DIV(float=right,width="200px")}^Related Topics *Related link *Related link *Related link *Related link^{DIV} ;__Overview__:Short description of the page including why you would need it. ;__To Access__:From the ((Administration Home)) page, click __Icon__ {img src=pics\large\icon-configuration.png alt="Icon"}. %%% or %%% Select __Foo > Bar__ from the default Tiki menu. ;__Notes__:Some important notes or considerations for the page (including any prerequisites). ;__Tabs__:This page contains the following tabs:{toc title=""} ~tc~Each tab on the page should be a separate wiki page, within the structure, as a child of the main page~/tc~ {TABS(name="Feature",tabs="6.x | 5.x | 4.x")} !! Tab Name Use this tab to... {IMG(src="...",thumb="y",width="350",desc="Tab name",alt="Tab name",imalign="center")}{IMG} {FANCYTABLE(sortable="y",colwidths="25%|65%|10%",colaligns="left",colvaligns="top",head="Field | Description | Default")} Lorem ipsum | Lorem ipsum dolor sit amet, consectetur adipiscing elit. | Quisque {FANCYTABLE} {TABS}
- Tiki templates can not be "re-applied" to existing pages.
- that's why we need to count on the wisdom of the crowds, which will keep editing pages even after we (read: a few benevolent users/editors/admins) restructure the content in doc.t.o ...
- Beauty is in the eye of the beholder
Proposed Menus
Menus should use PHPLayers ('cause I think they look nicer, 😊 )
Side Menu
- Introduction
- Installation
- Configuration
- Features
- Wiki
- _
- _
- Admin Panels
- Troubleshooting
- Tuning TikiWiki
- Mods
- Third-Party Code
This is really a simplified "table of contents" of the entire doc "book". I wonder if there's a way to automatically create a menu based on structure.... Otherwise it will be a lot of work to fill in the items in the Features section.
Xavi: That should be possible through using a module menupage, and in that page, add a {toc} while setting the structure id and depth level... 😉 Those params should be described in http://doc.tiki.org/toc
- Hm.... doesn't seem to support PHPLayer or Suckerfish menus, though. It makes simply a bulleted list, right? I would much prefer to have actual menu buttons/links. I think they'll look much better. (IMHO) -ricks99
- Hehe guys I did in tw >=4.0 (menu structureId=xx} it can work as a tw menu or a css menu 😉 - and with the param menu_cookie=n, onlt the part where you are in is open - perhaps still some bugs for some settings - but works pretty well with no sefurl ... sylvieg 😉
tobi_h: I was wondering what the difference is between the Side Menu's Introduction, Installation, and following, in comparison to the Top Menu's Get Started Section. I ask since I would like to suggest an additional item "Operation & Maintenance", covering information on chores like tuning, logging, backups, and upgrades/updates. I hope this is a good place to put this, otherwise sorry in advance. 😊
- Maybe within the Tuning Tiki section? (ricks99)
Torsten: If you want to use kind of an 'automatic menu', which I refer sometimes as 'magic menu', you can use the "module_menu", where you optionally can use either the parameter menuId or the parameter structureId.
Using a structureId, you are getting a 'CSS-Menu', which is working eactly as a normal 'CSS-Menu', but the 'menu' gets its menu items out of the "toc" of the structure.
If you use the parameter type=horiz, the first level of the toc will be horizontal, whilst the lower levels stay vertical drop down on hover.
Adding pages to the structure automattically adds a link to the page in the menu at the same level, where the page is located in the structure.
Open Questions
Versioning
- Use TAB or VERSION plugin?
- This is a no-brainer, isn't it? - the version plugin (is it still maintained?) needs a page refresh to show other-version content; tabs don't, so other-tab content displays immediately.
- Well, that also means that pages with TAB will be slower to load, as they'll have all images and linked content. Pages with VERSION will only load the items necessary to display. I can see +/- for either. And I'm not 100% how each can be printed/PDF'd. (ricks99)
- Good point, Rick. Maybe it would be good to do some testing to see which way works best. My gut feeing is that, unless there are a lot of rather big images, the load time difference wouldn't be that noticable (watching the page load in Firebug shows how much 'invisible' overhead + basic layout stuff dominates the file transfers).
- for me (xavi): +1 to have tab plugin: I don't mind reading something else when I'm opening new pages in new browser tabs. But once I move tab to that page because I see it fully loaded, I get the benefit that I don't have to wait some more time after I click in the link of a subpage to find the content I was interested in reading...
And of course, much better if all tabs could be set to a title (from all pages in the structure) in a single go/click.
- This is a no-brainer, isn't it? - the version plugin (is it still maintained?) needs a page refresh to show other-version content; tabs don't, so other-tab content displays immediately.
- How does this affect ability to print/PDF?
Previous work
[+]
Deleted structure
Here is the tree of the old deleted structure Documentation TOC, in case of...
- [+]Copy to clipboardIntroduction Goals Social Contract Tiki2 Tiki3 Tiki4 Tiki5 Tiki6 Tiki7 Tiki8 Tiki9 Tiki10 Tiki11 Tiki12 Installation Requirements Download Linux Install on Debian Install on Gentoo Performance Unified Index Manual Installation Windows Desktop Install Windows Server Install Advanced Settings Apache Clean URLs MultiTiki MultiTiki Manual Installation TRIM->Tiki Remote Instance Manager ImageMagick Install GraphViz Install mod_security Robots Exclusion Protocol Upgrade Upgrade 1.8.x to 1.9.y Upgrade 1.9.x to 1.9.y Upgrade 1.9.x to 2.x Upgrade 2.x to 3.x Upgrade 3.x to 3.latest Upgrade trunk Security Admin Configuration Initial Configuration Menu HOWTO Profiles Data Channels Features Wiki Plugin Alias Plugin Security Plugin Approval Using Wiki Pages Wiki-Syntax Links Wiki-Syntax Lists Wiki-Syntax Images Wiki-Syntax Text Wiki-Syntax Separators Wiki-Syntax Tables Wiki-Syntax Special Characters Advanced Wiki Syntax usage examples Wiki Argument Variables Wiki Config Wiki Page Staging and Approval Flagged Revisions Edit by Section Wiki Details Wiki Plugin PluginAgentinfo PluginAlink PluginAname PluginAnnotation PluginAnnotation example PluginArticle PluginArticles PluginAttach PluginAuthor PluginAvatar PluginBack PluginBacklinks PluginBanner PluginBloglist PluginBox PluginButton PluginCalendar PluginCarousel PluginCategory PluginCategoryTransition PluginCatOrphans PluginCatpath PluginCenter PluginChart PluginCode PluginAddFreetag PluginAddRelation PluginAddToCart PluginAddToGoogleCal PluginAdjustInventory PluginColorbox PluginComment PluginCopyright PluginCountdown PluginDBReport PluginAppFrame PluginArchiveBuilder PluginDialog PluginDiv PluginDl PluginDraw PluginAttributes PluginEquation PluginEvents PluginExercise PluginExtendCartHold PluginBigBlueButton PluginBlipTV PluginFade PluginFancylist PluginFancyTable PluginFavorite PluginFile PluginFiles PluginCartMissingUserInfo PluginFlash PluginFootnote PluginFootnotearea PluginFtp PluginGalleriffic PluginGauge PluginGoogleDoc PluginGroup PluginGroupList PluginContent PluginContributionsDashboard PluginConvene PluginGroupMailCore PluginCookie PluginGroupstat PluginCustomSearch PluginDataChannel PluginHTML PluginHtmlFeed PluginHtmlFeedLink PluginIframe PluginImage PluginImg PluginInclude PluginInvite PluginJabber PluginJq PluginJS PluginLang PluginLastmod PluginList PluginListExecute PluginListpages PluginLsDir PluginMail PluginFont PluginMaketoc PluginMcalendar PluginFreetagged PluginMediaPlayer PluginMemberList PluginMiniQuiz PluginGetAccessToken PluginGoogleAnalytics PluginModule PluginGoogleMap PluginMono PluginGroupExpiry PluginMouseover PluginMWTable PluginMySpace PluginNow PluginObjecthits PluginPageTabs PluginParam PluginPerm PluginPoll PluginPref PluginProposal PluginQuote PluginR PluginRealnamelist PluginRedirect PluginKaltura PluginRSS PluginSharethis PluginSheet PluginPerspective PluginShowpages PluginSkype PluginMap PluginSlider PluginSlideshow PluginSmarty PluginSnarf PluginMemberPayment PluginSort PluginSplit PluginSQL PluginStat PluginSub PluginSubscribeGroup PluginSubscribeGroups PluginSubscribeNewsletter PluginSup PluginPayment PluginPluginManager PluginTabs PluginProfile PluginTag PluginThumb PluginTimeline PluginRandominclude PluginTitleSearch PluginRcontent PluginTimesheet PluginRegex PluginRegex Example PluginRelations PluginToc PluginRemarksbox PluginReport PluginTowTruck PluginTr PluginScroll PluginTracker Plugin Tracker Advanced PluginTrackerCalendar PluginTrackercomments PluginTrackerFilter PluginTrackerItemCopy PluginTrackerItemField PluginTrackerList PluginTrackerPasscode PluginTrackerPrefill PluginTrackerStat PluginTrackerTimeline PluginTrackerToggle PluginTransclude PluginTranslated PluginTwitter PluginUsercount PluginUserlist PluginVersions PluginVimeo PluginVote PluginVotings PluginWebDocViewer PluginWebservice PluginWMV PluginWYSIWYG PluginYouTube PluginTrackerIf PluginTextlink PluginTrade PluginUserlink PluginUserpref PluginWantedPages PluginWatershed Wysiwyg Wysiwyg Editor User Wysiwyg Editor Details History Interoperability Image Gallery Image Gallery User Image Gallery Config Image Gallery Details Articles Article Generator Article User Articles Config Article Details Blog Blog User Blog Config Blog Ref File Gallery File Gallery User File Gallery Config Search within files File Gallery for Images Batch Upload elFinder Forum Forum User Forum Admin Forum Details Forum and Mailing List Synchronization Deliberation Directory Directory User Directory Admin Directory Details FAQ FAQ User FAQ Admin Quiz Quiz User Quiz Admin Trackers Tracker User Tracker Admin Tracker Details Creating a Tracker Adding fields to a tracker Tracker Field Type Action Tracker Field Attachment Field Auto-Increment Field Category Tracker Field Checkbox Tracker Field Computed Tracker Field Selector Tracker Fields Country Selector Group selector IP selector Page selector User selector Currency Amount Tracker Field Date Tracker Fields Drop Down - Radio Tracker Field Dynamic items list Email Tracker Field Files Tracker Field Freetags Tracker Field Google Maps Tracker Field Header Tracker Field Image Tracker Field Icon Tracker Field In Group Field Items List and Item Link Tracker Fields Numeric Tracker Field Rating Tracker Field Relations Tracker Field Stars Field Static Text Tracker Field Subscription Tracker Field System Tracker Field Text Tracker Field Textarea Tracker Field URL Tracker Field User Groups User Preference Field How to change tracker field types Adding items to a tracker Tracker Field Validation Searching tracker items User Tracker Group Tracker Pretty Tracker Pretty Tracker in a Wiki Page Linking trackers Export trackers Tracker Inline edit Import Trackers Tracker Synchronization Spreadsheet Spreadsheet Functionality Spreadsheet Interface Spreadsheet Graphics and Charts Spreadsheet jq Surveys Survey User Survey Admin Survey Details Newsletters Newsletter User Newsletter Admin Newsletter Details Newsletter Article Clipping Stats Stats User Stats Admin Referer Stats Calendar Calendar User Calendar Admin Js Calendar Microformats Integrator Integrator User Integrator Admin Integrator Details Category Category User Category Admin Categories Details Category Transitions Banners Banner User Banner Admin Areas Module Module Admin Module Settings Interface Module Settings Parameters Creating User Modules Assigning Modules Index of Modules Module action_calendar Module action_similarcontent Module babelfish_links Module freetags_morelikethis Module logo Module map_edit_features module menu Module share Module share Module adsense Module articles Module assistant Module article_archives Module calendar_new Module categories Module category_transition Module change_category Module breadcrumb Module comm_received_objects Module credits Module directory_last_sites Module directory_stats Module directory_top_sites Module events Module facebook Module featured_links Module forums_best_voted_topics Module forums_last_posts Module forums_last_topics Module forums_most_commented_forums Module forums_most_read_topics Module forums_most_visited_forums Module freetags_most_popular Module google Module last_actions Module last_articles Module last_blog_posts Module last_category_objects Module last_created_blogs Module last_created_faqs Module last_created_quizzes Module last_files Module last_file_galleries Module last_images Module last_images_th Module last_image_galleries Module last_modified_blogs Module last_modif_events Module last_modif_pages Module last_modif_tracker_items Module last_submissions Module last_tracker_comments Module last_tracker_items Module last_validated_faq_questions Module last_visitors Module last_youtube_playlist_videos Module live_support Module logged_users Module login_box Module menupage Module messages_unread_messages Module minichat module months_links Module num_submissions Module old_articles Module online_users Module quick_edit Module random_images Module random_pages Module search_box Module search_new Module search_wiki_page Module semantic_links Module shoutbox Module since_last_visit Module since_last_visit_new Module switch_lang Module switch_lang2 Module switch_theme Module tail Module top_active_blogs Module top_articles Module top_files Module top_file_galleries Module top_forum_posters Module top_games Module top_images Module top_images_th Module top_image_galleries Module top_objects Module top_pages Module top_quizzes Module top_visited_blogs Module top_visited_faqs Module trackerhelp Module twitter Module upcoming_events Module user_blogs Module user_bookmarks Module user_image_galleries Module user_pages Module user_tasks module groups_emulation Module users_list Module users_own_rank module users_rank Module whats_related Module who_is_there Module wiki_last_comments Module wikistructure Chat Chat User Chat Admin Live Support Live Support User Live Support Admin Live Support Details Contact us Map Maps User Maps Admin Maps Install Maps Config Geolocation Gmap Gmap User Gmap Admin Gmap Details Mobile Mobile Tiki User Structures Structure User Structure Admin Structure Details Raw page display Slideshow Slideshow User Slideshow Admin Slideshow Details JQS5 Comments Comment User Comment Admin Inline comments Comment Moderation Contribution Contributions by Author Communication Center Draw Spellcheck Spellcheck User Spellcheck Admin Redirect to similar wiki page HTML Pages Dynamic Content Dynamic Content Admin Dynamic Variable Tags Feeds Feeds User RSS Admin RSS Feeds Details Html Feed TextBackLinkProtocol Score Score Admin Score Details Karma Score vs Karma Shoutbox Shoutbox User Shoutbox Admin Search Search User Search Admin Search Details Search Stats Referrer Search Highlighting Search and replace Syntax Highlighter Timesheet Friendship Network MyTiki MyTiki Admin MyTiki Details Webmail Contacts Inter-User Messages Notepad Task User Files User Calendar User Menu User Preferences Bookmarks User Modules Watch Daily Reports Group Watches Group Alert User Action log User Levels Tell a Friend i18n Multilingual Module Multilingual trackers Multilingual Menu UTF-8 Character Encoding Multilingual Wiki Interface translation Interface translation (old) Interactive Translation i18n Admin Machine Translation Multilingual Article Multilingual Structures Multilingual categories Multilingual tags Payment Community Currencies Batch Cron Job to Rebuild Search Index Rating Advanced Rating Share Web Services Workspace Workspace UI Namespaces Social Networks Tiki Importer MediaWiki Importer WordPress importer Reports Metrics Dashboard Zotero Accounting Activity Stream Admin Panels Performance Admin Panel Compression General Admin Login Config External Authentication phpBB Authentication LDAP authentication PAM authentication Shibboleth Authentication OpenId CAS Authentication Users Groups Management Group Transitions Permissions Admin DSN Banning Link Cache Content Templates Cookie Cookie Consent Edit Templates Edit CSS Featured Links Custom Home Mail notifications Mail-in Maps Config Menu Theme Control Theme Generator Phpinfo Logs Server Check Permission Check System Admin System Log Intertiki Contribution Admin Wysiwyg Editor Admin Text area Smileys AutoLinks Link Cache Toolbar External Wikis Token Access System Configuration Docs Ajax Live preview Profiles Semantic Page Alias Semantic Admin WebDAV WebDAV access to Wiki Pages Groupmail Screencast Ustream Watershed Content Organizer Tuning Tiki Design Themes Smarty Templates Theme Layout Schema Customizing Themes Template tricks Mods Mods User Mods Admin Mods Details Hacking Code Performance Debugger Console TikiTests MinifiedScripts Content delivery network Amazon CloudFront ToolBox Multiplatform Tools Eclipse Linux tools Windows tools Mac Tools Customize Import-Export Annexes About the Tiki Documentation Welcome Authors Tiki Manual of Style Documentation Lifecycle Documentation Templates Feature Page Template Documentation Status htaccess php.ini Printing the Documentation Tikiwiki FAQs Mods List Mods Type Avatars Mod dragonballz Mod gnumes Mod goldorak Mod mcdonald Mod xmen Mod all avatars Mods Type Features Mod aulawiki Mod cc Mod import-phpwiki Mod tikidav Mod tinvoice Mod userprefstats Mods type goodies Mods clean structure Mods Type Lib Mod fpdf Mod fpdf_bitstreamvera Mod fpdf_freefonts Mod jpgraph Mod mozilla2ps Mods Type Menus Mods Type Modules Mod blogroll Mod calculator Mod clock Mod extcalculator Mod join Mod plazes Mod worldclock Mods Type Services Mod mailman Mods Type SQL Mods Type Taglines Mod damian2 Mods Type Themes Mods Type Wikiplugins Mod author Mod phpfreechat Mod ebay Mod flowplayer Mod formula Mod gmap Mod mindmap Mod phplot Mod plazes Mod svg Mod wikigraph Mod xspf_player Tiki Community Tiki History Changelog 3.x Changelog 2.x Changelog 1.9 Changelog 1.8 Changelog 1.7 Changelog 1.6 Changelog 1.1 Changelog 1.5 Changelog 1.4 Changelog 1.3 Changelog 1.2 Changelog 1.0