talk:Manual of Style | Documentation for Tiki Wiki CMS Groupware

Recommend that relevant parts be merged into the TikiWiki Manual of Style page and this one deleted.

The discussion on this page pertains mainly to Documentation Structure actually.

MoS page should cover the details and fine points, can be expanded to cover the proper use of inpage menus, screen shots, faqs, etc.

doc site needs some major css teaking. heading levels after 2 should be indented, h2 should be smaller, perhaps including a horizontal rule and edit by section.

Templates are/should be the major tool for style control. Registered users should be able to punch a button and add (below any existing content) a preformatted chunk of content.

Thacker's Laws of Documentation.

Answer my question. Do not make me wade through reams of extraneous material
Optimize my searches. Get me as close to the right entry as you can with my keyword
Keep the pages short, do not make me scroll from Minneapolis to Dallas for an answer
Use clear, concise, business quality language.
Do not editorialize. Write from a Neutral Point of View
Always give an example
Screenshots rule

smaller, more targeted pages are preferable over large monolithic pages. They are easier to maintain, categorize, and will serve our target audience better. Since a page can belong to more than one structure, they can be re-used where necessary.

Laws of the knowledge base

nobody talks about knowledge bases, the point is only having one. (doc? dev? org?)
without a common vocabulary, you can't communicate.

define all significant terms
related link to the terms to the objects/concepts
related link to from the objects/concepts to the advanced objects/concepts.
inline link back to terms, always.

don't force structure on the learning (except to)
create lists of categorized objects.
the specific must always link to the general.
use hard redirects and (soft) disambiguators to restrict the vocabulary (did you mean?)

please explain a soft disambiguator?

if someone linked it, it should exist. (do not remove open links, fill them in)

knowledge is built always as a pyramid, from the broadest foundations (first) to the pointiest details. Teaching the details without the foundations is a mutual pain.

Sounds good. What's the bottom of the tiki pyramid

(accurate) terminology matters.
- the biggest problem i have had with learning trackers, i reckon, is that they are misnamed. They are a Forms and Reports feature.
programmers (experts in general) are often the least helpful explainers. (fishes that can't see the water)