Author Coffeeshop

Posted by alain_desilets Tue 08 May, 2007 13:57 GMT-0000 posts: 2 ☆

> Use this thread to discuss the page:: Change the Appearance of Tikiwiki

Hi folks. Thank you for making changes to my admin tutorial pages.

I just wanted to describe a principle I am using to write these pages, so that we can come to a common understanding.

As a newbie to Tiki, I find the existing documentation very hard to use because it's structured according to the system instead of according to the task.

In other words, the documentation describes the features of the system, in the order that they tend to appear in the UI.

What I need is something that talks not about features, but about common admin tasks I need to do. So I am trying to write my tutorials that way.

For example, instead of having a header that says:

• Select a theme

I will have a header that says:

• Change the general appearance to something you find more pleasing

Selecting a theme is just a way to achieve that goal.

Many users see the default Tiki look and think "Yuck, that's ugly, how can I change it"? They don't know that what they need to do is select a theme, so a header that says "Select a theme" doesn't help them as much as a header that says "How to choose a look that you find pleasing" or something like that.

Posted by mlpvolt Wed 09 May, 2007 13:53 GMT-0000 posts: 5 ☆ ☆ ☆

Three conventions i think are or should be defined in the manual of style

1. Page names should be as short as possible.

2. Which verb tense is advised?

3. there can be many overlapping pages about a topic but if they all link to the same keywords eg. theme, they can eventually be found and refactored.

Posted by Gary Cunningham-Lee Wed 16 May, 2007 02:03 GMT-0000 posts: 36 ☆ ☆ ☆ ☆

I think if we see the docs here as a reference, then it makes sense to have it organized as a directory with a page (more or less) for each Tiki feature. The closer we get to a one-to-one correlation (feature::explanation), we can be sure everthing is documented. This would be a problem if information is structured according to task rather than feature.

If there is, first of all, a dictionary-like set of pages that correlate to Tiki features, etc. this provides the basic knowledge base for Tiki use.

Then the place for tutorials is in addition to that set, I'd say. The tutorials can reference the feature-specific doc pages as background or detailed process information, but can be written from a task-oriented perspective.

So tutorial pages would complement feature description pages. Perhaps as Alain's pages show, the page titles are more like statements rather then single-word or phrase type titles of the basic doc pages.

I think the existing doc structure should stay feature set focused, and tutorial type pages should perhaps be a separate parallel structure that links as needed.

Just my two cents/euros. ;-)

Posted by Gary Cunningham-Lee Wed 16 May, 2007 02:17 GMT-0000 posts: 36 ☆ ☆ ☆ ☆

> Use this thread to discuss the page:: Change the Appearance of Tikiwiki

About the content of Change the Appearance of Tikiwiki specifically, when themes.tw.o was set up, marclaporte and I had thought it would be good to offload theme-specific documentation from tikiwiki.org and doc.tikiwiki.org to that site, to spread the server load around and to keep relevant information in one place as much as possible. That hasn't happened totally, but there's been some effort there, and the idea is valid I think.

For that purpose, it's necessary to decide where to draw the lines. I think doc.tikiwiki.org is essentially for information on how to use the standard Tiki package. The more a page gets into extending Tiki, the more it belongs at a specific thematic site, such as themes.tw.o or edu.tw.o, etc. (I'd like feedback on this.)

For this reason, I'd say this particular page should perhaps just mainly point to the already existing pages on this topic at themes.tw.o. There's no point in reinventing the wheel at several Tiki sites, having to update them, etc. I may edit it myself to accomplish that (there are also some content inaccuracies, etc.). Alain might want to take a look at themes.tw.o to see what's been done over there and what could be contributed.

If users don't know about the Tiki themes site, then we need some education/PR to improve that. Links from tw.o and doc.tw.o can help there.