cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d...@cocoon.apache.org
Subject [Cocoon Wiki] Updated: ExtremeDocumentationOverhaul
Date Sun, 14 Nov 2004 07:16:13 GMT
   Date: 2004-11-13T23:16:12
   Editor: DavidLeangen <dleangen@canada.com>
   Wiki: Cocoon Wiki
   Page: ExtremeDocumentationOverhaul
   URL: http://wiki.apache.org/cocoon/ExtremeDocumentationOverhaul

   no comment

Change Log:

------------------------------------------------------------------------------
@@ -1,7 +1,7 @@
 = Page Summary =
-- TARGET-AUDIENCE: '''*anybody*'''[[BR]]
+- TARGET-AUDIENCE: anybody[[BR]]
 - COCOON-RELEASES: 2.1.5[[BR]]
-- DOCUMENT-STATUS: '''*draft*'''[[BR]]
+- DOCUMENT-STATUS: draft[[BR]]
 - AUTHOR: DavidLeangen[[BR]]
 - AUTHOR-CONTACT: mailto:dleangen<at>canada.com[[BR]]
 
@@ -42,7 +42,7 @@
 
  * Explain our vision of what the site should be; and
  * Act as the basis of a new Cocoon website; or
- * Act as the basis of a new project external to Cocoon; or even
+ * Act as the basis of a new documentation project external to Cocoon; or even
  * Act as the basis for a commercial project
 
 == General Principles ==
@@ -58,6 +58,7 @@
 
  * Eliminate the wiki, or have page timeouts
  * Be very concise, ruthlessly deleting unnecessary content
+ * Think in broader terms about who uses the site
  * Focus more on what the user wants to accomplish than on what Cocoon does
  * <to be continued>
 
@@ -69,20 +70,19 @@
 
 Proof of the need of this is the large number of unused pages on the wiki. Although great
effort has been made to clean up the wiki, inevitably, it will again become messy after a
few more months of use.
 
-== Proposed Content Structure ==
+=== Target Audience ===
 
-This section explains the approach we will take to determine what the structure of the new
site should be.
+Currently, the site is targeted towards people with programming skills who plan to use Cocoon
themselves for development. We believe, however, that this approach is too narrow and does
not help to promote Cocoon for mainstream use.
 
-=== Fundamental Questions ===
+Again assuming that many of our users are commercial, in many cases, if not most, programmers
do not make the actual decision as to what product to use. Rather, somebody higher up the
ladder determines what product will be used. This person or persons have many factors to consider
beyond nice technical design and any final decision is based on perceived risk versus reward,
with an emphasis on the word "'''perceived'''".
 
-To determine what the structure should be, we first need some way of being able to answer
these fundamental questions:
+Or, a user may be a reporter who has heard about Cocoon and wants to report on it. In many
cases, the reporter has little technical knowledge: we need to spoon feed the information.
If the reporter cannot understand what we're trying to do, no article will ever get written.
However, we want to reach not only developers, but also the decision-makers who's interests
are more commercial than technical. We therefore want to make the Cocoon message simple enough
to be passed on by the non-technical. As it stands, the information is too technical.
 
- * What type(s) of user(s) will be visiting the website?
- * What is the user's goal?
- * What, precisely, do we want to communicate?
+In any case, one fundamental principle holds true: if people cannot relate to the content,
if they cannot understand what we're saying, they will simply move on. First impressions are
important.
 
+We believe, therefore, that the intended audience must be expanded and the content adapted
in consequence to relate better to each of the target user profiles.
 
-=== Task-based ===
+=== Task-based Content ===
 
 Navigation of the site should be task-based and not content-based. What we mean by this is
that content should appear according to what the user is trying to achieve, rather than according
to the information we want to present. This means, counter to the fundamental programming
axiom of "once and only once", that information may be duplicated. Note, however, that the
information source need not be duplicated: only the resulting HTML.
 
@@ -94,5 +94,20 @@
 
 
 Each of these types of users have not only very different goals, but different skill sets.
What they want from the site is very different. Using the "once and only once" approach, it
is simply not possible (except using some business logic in a dynamic site, which is not what
we're proposing here).
+
+<This could be a complete article on its own...>
+
+== Proposed Content Structure ==
+
+This section explains the approach we will take to determine what the structure of the new
site should be.
+
+=== Fundamental Questions ===
+
+To determine what the structure should be, we first need some way of being able to answer
these fundamental questions:
+
+ * What type(s) of user(s) will be visiting the website?
+ * What is the user's goal?
+ * What, precisely, do we want to communicate?
+
 
 == <to be continued> ==

Mime
View raw message