Date: 2004-11-13T23:16:12 Editor: DavidLeangen <[EMAIL PROTECTED]> 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> ==
