doctwo Revamp

Tiki Doc Content Reorg Proposal

pianoliv: This proposal from 2011 is still being worked on (2013), don't hesitate to join in!

1.1. Content reorg - Tiki Doc Suite
1.2. Ease contribution
Open Questions
Previous work
Deleted structure

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: 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.
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.
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 Started
Welcome to TikiWiki. If you are new, start here: Get Tiki the current release. Install or Upgrade your Tiki. Configure the features. See what's new in TikiWiki 2.0.

Get Help
Having problems? Check here first: Frequently Asked Questions (FAQs) Troubleshooting Tutorials and Videos Forums Review the complete documentation.

Become an Author
The TikiWiki documentation is always a work in progress — you can help! Register with the Tiki community, then login. Check the Documentation Status page to see where help is needed. Use the documentation templates and add your knowledge! We always welcome new authors!

Learn More
Did you find a problem with the documenation? Let us know: Become an author and fix it! Log it on the documentation bug tracker. Discuss it on the documentation forum. Tell us on the #tikiwiki IRC channel. Join the user community!

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?
- TikiTV ?
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:
1. Polls
2. Password
3. Structure
4. Edit
5. Feature search
6. anchor
7. ldap
8. maketoc
9. categories
10. 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.
- Agreed (ricks99)
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)

Deleted structure

Here is the tree of the old deleted structure Documentation TOC, in case of...

[+]