Loading...
 
Skip to main content
2
Page actions
Print

doctwo Revamp

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

  1. Reorganize the content. Instead of single guide/structure, create multiple smaller guides.
  2. 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: PDF 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: PDF 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:

  1. The pages will "look" as though they belong together
  2. Makes Tiki look more "professional"
  3. Easier to see what's missing
  4. 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

[+]

Deleted structure

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


[+]


Page last modified on Friday 20 September 2019 17:50:08 GMT-0000
History Files 2
Similar Slideshow