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
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: half way (see this forum thread
Tiki Administrator Guide
- Primary target: Tiki Admins
- Secondary target: Tiki Community
- Organization: Most common Admin tasks, grouped by Feature
- Completion: to do (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.
- 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
Menus should use PHPLayers ('cause I think they look nicer, ๐ )
Side Menu
- Introduction
- Installation
- Configuration
- Features
- 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.tikiwiki.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)
1.3. 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.
- How does this affect ability to print/PDF?
Previous work
[+]
The information below, was part of the general revamp, completed for Tiki 3.
The upcoming 3.0 release represents a huge step forward for TikiWiki... both in features and refinement.
I think it may be time to move doc.tw.o forward, too.
Home Page
Home Page Completed — Feb 26, 2009
The current Home Page presents a lot of information — maybe too much. There are nearly 30 links and (IMHO) no real organization of "where should I go?", or to borrow from Micrsoft, "What do you want to do?"
I propose a simplified, streamlined Home Page that present four "types" of information.
|
|
Get HelpHaving problems? Check here first:
|
|
|
Learn MoreDid you find a problem with the documenation? Let us know:
|
Documentation News
Use the ARTICLES module to show the last 10 news items.
|
|
Recently Updated Pages
Use the LAST_MODIF_PAGES to show the last 10 (or 20) modified pages.
|
|
TikiWiki News
RSS from tw.o
|
Get Started
This is the assumed starting point. Give visitors starting points of how get Tiki, how to install Tiki, and how to configure tiki.
Get Help
This is where folks go looking for answers. Give them links to the FAQs, troubleshooting guides, and the support forums.
Authors
This is for folks who want to improve the docs. Give them directions on how to contribute.
Learn More
This is for "everything else."
Top Menu
- About Tiki
- Get Started
- Get Help
- Become an Author
- Welcome Authors
- Register (external link)
- Documentation Status?
- Templates
- Editor Board
(notice how the top menu mimics the four boxes from the Home Page....)
Modules
Left
- Switch language
- Side Menu
- Doc Project (?!?)
This is for things about TW and the doc project, downloads, stats, etc.
Right
- Login (Anonymous only & Admins, in case we need to help/check problems of a specific user)
- Translation assistant
- Most popular pages
- Tags
- freetag (Reg only)
- Most popular searches
- New since last (Reg only)
Other changes/suggestions
- Can we remove the drop-list in the search module (at top)? Is a new user going to know that searching for "articles" isn't really what they want?
- Remove the Search by Page Name module. If a user needs help, do they really know a specific page to search for?
- Xavi: not necessarily, but while search is not improved (and have boolean search working), I suggest to keep it. It's been useful many times to find pages, whereas through the generic search that was not easy...
- Remove the Keywords module — let's use Freetags instead.
- Xavi: I see the intention from marc to have that parallel list between dev and doc. I would say to keep it for registered?
- I see your point, but I still question the list of "keywords." As an end-user (who simply wants help with a specific feature) it seems like a lot of "noise" to me. There's a lot of inconsistencies in the list: some have version numbers, some are full links, there's terms like "dogfood" (which mean nothing to an end-user looking for docs), etc. Again, just my $0.02. - ricks99
- I love the fact that TW for Smarties is a Featured Link — are there others?
- Remove the Registered module. Instead, let's create a page (or section of the Welcome Authors) that explains that registration is via InterTiki.
- Remove the Last Changes module. Instead we show the top search queries. This will have to be manually created... anyone know how to do this automatically?
Xavi: this is useful to me as editor/contributor. I'd vote to keep it for registered.
lindon: One idea is to keep/add together somewhere things useful to know for review/editing: Last Changes, Most Popular Pages, Last Images Uploaded, Most Searched (if doable)
For the curious, the top 10 search terms for the 2 week period Feb 1-14, 2009 (from Google Analytics) are:
- Polls
- Password
- Structure
- Edit
- Feature search
- anchor
- ldap
- maketoc
- categories
- creating module
- Remove the Doc News module. It is now on the Home Page (only)
- Categories vs Tags
The way I see things, tags are for the end-users — describing what the content is about. Categories are for writers, describing what the status of the page is.
- Have a "cookbook" or "best practices" section that just doesn't describe the technical aspects but provides actual examples. In reviewing the current documentation, I have found a lack of actual examples on the documentation pages. This would probably reduce the searching and frustration newbies have trying to sift through the forums. These sections can be part of the documentation on such things as WikiText or Plugins/Mods such as {maketoc} and the use of dynamic content or they can be a separate section of the documentation.
- I believe this was the purpose of the Basic docs project. Not sure of its status... (ricks99)
- All pages should enable the reader to look at the source. This goes a long way in giving actual examples of how to build nice looking WikiPages.
- Would be helpful to have a link to Articles, Trackers, Image Galleries, MyTiki, Spreadsheet features on the documentation site (the actual features, not the documentation about the features). For example, there's no link right now for a user to go to their MyTiki page (unless I missed it!) -lindon
- On this, I disagree. I still maintain that the doc.tw.o should not be as "open" as the community (tw.o) site. The overwhelming majority of visitors to doc.tw.o are simply looking for information — from the wiki pages. For actual content providers I can see expanding the "author's" menu items (perhaps as an additional module). (ricks99)
- You're right, I really meant for authors - would have been good if I'd said that! ;>) (lindon)