Edit detail for ZwikiDocsDiscussion revision 1 of 1

1
Editor: simon
Time: 2006/02/07 18:52:45 GMT+0
Note:

changed:
-
From SimonMichael Mon Feb 16 19:47:47 -0800 2004
From: SimonMichael
Date: Mon, 16 Feb 2004 19:47:47 -0800
Subject: next step
Message-ID: <[email protected]>

The "book" outline at ZWiki was a step forward and awaits better organization. 
I want us to try a different approach as well/instead - starting with the HelpPage (& FrontPage), 
develop a very clean and clear set of "Zwiki Help" pages. These are to exclude 
historical discussions, long-winded explanations and rambling discourse, 
and they will be organized in the 
"silverorange help style":http://demo.silverorange.com/help/projects_orgs_people :

- fewer, longer pages; a page should provide somewhat complete coverage for a topic

- pages are made up of numbered, named, bite-sized nodes

- these are grouped as basic, intermediate and advanced

- a table of contents at the top of the page

I'm not sure how this plays with our subtopics feature.

I've made a start at HelpPage. I won't try to automate any of this just yet, but obviously that would be great. For STX I imagine using simple first-column headings to define nodes, special HTML comments to mark the basic/intermediate/advanced sections, and generating the table of contents from there.

From SimonMichael Mon Feb 16 20:57:35 -0800 2004
From: SimonMichael
Date: Mon, 16 Feb 2004 20:57:35 -0800
Subject: risks
Message-ID: <[email protected]>

Risks: losing wiki simplicity and making more work for ourselves.

From simon Tue Feb 17 10:36:30 -0800 2004
From: simon
Date: Tue, 17 Feb 2004 10:36:30 -0800
Subject: next step
Message-ID: <[email protected]>
In-reply-to: <[email protected]>

I've added some tables of contents, or simply the basic/intermediate/advanced headings, to some of the key doc pages (those linked on the front page). I think it's a win; even with just the headings, you get an immediate sense of whether you want to be looking at that page or not. Possibly we could colour-code these blue/red/black like ski slopes. I could definitely use some kind of macro for these now. 


From SimonMichael Sat Mar 13 19:00:38 -0800 2004
From: SimonMichael
Date: Sat, 13 Mar 2004 19:00:38 -0800
Subject: levels of difficulty
Message-ID: <[email protected]>

Perhaps the current ski-slope style table of contents-headings are a bit too much ? We don't want pages that are over-busy. And multiple levels of difficulty within a page may be overkill, a single difficulty level and/or contents list at the top of the page might be better.

From SimonMichael Mon Jun 7 18:14:59 -0700 2004
From: SimonMichael
Date: Mon, 07 Jun 2004 18:14:59 -0700
Subject: zwiki docs status
Message-ID: <[email protected]>

Haven't touched those level of difficulty headings yet..

We are using page hierarchy quite heavily. I've just moved the three how-to pages under the single HowTos. FrontPage is acting as the quick contents, ZWiki as the detailed contents for the documentation (and wiki contents for even more detail..) This seems to be working pretty well. Arguably we could chop out 50% of these pages without much loss from the zwiki documentation point of view.

I think we need more and fresher HowTos now. 

[FAQ] definitely needs some juice, but it never gets updated, not even by me; I'm not sure why. What should we do with it ?


From SimonMichael Mon Jun 7 19:12:55 -0700 2004
From: SimonMichael
Date: Mon, 07 Jun 2004 19:12:55 -0700
Subject: zwiki docs status
Message-ID: <[email protected]>
In-Reply-To: <[email protected]>

> Haven't touched those level of difficulty headings yet..

There, did something with them.


From SimonMichael Mon Oct 25 00:00:00 -0700 2004
From: SimonMichael
Date: Mon, 25 Oct 2004 00:00:00 -0700
Subject: reorg
Message-ID: <[email protected]>

Take a look at this page and let me know if you see any problems. The user and admin guide are to be more user- and task-centric, and their structure is reused for functional analysis and issue tracking. This will allow us to get bug counts and estimate quality in each area the user cares about, and prioritize the ones that matter most.


comments:

next step --SimonMichael, Mon, 16 Feb 2004 19:47:47 -0800 reply
The "book" outline at ZWiki was a step forward and awaits better organization. I want us to try a different approach as well/instead - starting with the HelpPage (& FrontPage), develop a very clean and clear set of "Zwiki Help" pages. These are to exclude historical discussions, long-winded explanations and rambling discourse, and they will be organized in the silverorange help style :

  • fewer, longer pages; a page should provide somewhat complete coverage for a topic
  • pages are made up of numbered, named, bite-sized nodes
  • these are grouped as basic, intermediate and advanced
  • a table of contents at the top of the page

I'm not sure how this plays with our subtopics feature.

I've made a start at HelpPage. I won't try to automate any of this just yet, but obviously that would be great. For STX I imagine using simple first-column headings to define nodes, special HTML comments to mark the basic/intermediate/advanced sections, and generating the table of contents from there.

risks --SimonMichael, Mon, 16 Feb 2004 20:57:35 -0800 reply
Risks: losing wiki simplicity and making more work for ourselves.

next step --simon, Tue, 17 Feb 2004 10:36:30 -0800 reply
I've added some tables of contents, or simply the basic/intermediate/advanced headings, to some of the key doc pages (those linked on the front page). I think it's a win; even with just the headings, you get an immediate sense of whether you want to be looking at that page or not. Possibly we could colour-code these blue/red/black like ski slopes. I could definitely use some kind of macro for these now.

levels of difficulty --SimonMichael, Sat, 13 Mar 2004 19:00:38 -0800 reply
Perhaps the current ski-slope style table of contents-headings are a bit too much ? We don't want pages that are over-busy. And multiple levels of difficulty within a page may be overkill, a single difficulty level and/or contents list at the top of the page might be better.

zwiki docs status --SimonMichael, Mon, 07 Jun 2004 18:14:59 -0700 reply
Haven't touched those level of difficulty headings yet..

We are using page hierarchy quite heavily. I've just moved the three how-to pages under the single HowTos. FrontPage is acting as the quick contents, ZWiki as the detailed contents for the documentation (and wiki contents for even more detail..) This seems to be working pretty well. Arguably we could chop out 50% of these pages without much loss from the zwiki documentation point of view.

I think we need more and fresher HowTos now.

FAQ definitely needs some juice, but it never gets updated, not even by me; I'm not sure why. What should we do with it ?

zwiki docs status --SimonMichael, Mon, 07 Jun 2004 19:12:55 -0700 reply

Haven't touched those level of difficulty headings yet..

There, did something with them.

reorg --SimonMichael, Mon, 25 Oct 2004 00:00:00 -0700 reply
Take a look at this page and let me know if you see any problems. The user and admin guide are to be more user- and task-centric, and their structure is reused for functional analysis and issue tracking. This will allow us to get bug counts and estimate quality in each area the user cares about, and prioritize the ones that matter most.