On Monday 18 November 2002 13:42, Diana Shannon wrote: >. . . > Hmm... You forgot > - FAQs > - Snippets > - topics (not implemented yet) >. . .
Waitwaitwait - too much top-level categories IMHO. I'm not talking about doc types here, but the website view on our documents. My vision is that, coming to the Forrestified site one sees these tabs: -Home -Concepts -Tutorials -Reference -Wiki More than this would be overwhelming I think. Maybe we need a better name for "Tutorials" but I think there shouldn't be so many categories, it is well-know than more than 7 points on a list of choices is too much. My list has 5, yours has 7 more which is too much I think (but we might be speaking from very different angles). Tutorials (for lack of a better name) would of use several doc types, but as a "doc subproject" or "doc category" Tutorials stands on its own I think. It's not reference yet, it is task-oriented docs as opposed to components-oriented docs. I've rewritten my proposal at http://outerthought.net/wiki/Wiki.jsp?page=CocoonDocsPlan, trying to differentiate better between "doc categories" and "doc types", what do you think? > I wouldn't combine Tutorials and How-Tos a single doc type. ok as far as doc types go, but users are not looking for doc types, they are looking for knowledge and they have no idea (at first) where they will find it. IMHO Navigation must be decoupled from doc types. >. . . > Also, I'm not sure I like a separate category for Concept docs. They > tend to be weak unless kept very general. >. . . If weak it must be a goal (maybe not top priority but still a goal) to improve them. What is Cocoon? How is it built? How is it used? What other similar products exist? General info like this is key in "selling" Cocoon IMHO. >. . .One of the major > problems with our current user guide is that we have separate pages for > concepts and component descriptions/details. It makes it **very** > difficult to navigate efficiently while learning. Agreed. Concepts documents will definitely need links to Reference documents to make this happen, or this will have to happen in the "documentation tracks" document. >. . . > > Navigation layer >. . . > I don't understand how this is a separate area. Do you mean road > map/learning trail docs? I mean website navigation, where we will need some form of sitemap between what the website visitor sees and the physical storage of our docs. Required if we want to store reference docs in the components source code directories. >. . .Can we have a consistent > URI pattern for mapping between existing docs and their Wiki-based notes > pages so it's easy to generate the links automatically? >. . . If you navigate to http://outerthought.net/wiki/Wiki.jsp?page=ThisPageDoesNotExistYet for example, JSPWiki kindly asks if you want to create the page (please don't create it or this example goes bust ;-) So simply adding a URL labeled "Wiki notes about this document" to every document published will do the job, after defining a clean mapping from website URLs to wiki notes URLS. But we *first* need to define permanent URLs for our docs, so I think this needs to wait for the Forrestization of our docs. >. . . > I've done a lot of work and thinking in this area. I'll be **happy** to > supplement your proposed text but I don't have time at the moment. Need > to finish my Forrest transition-related work. >. . . No worries, Forrestalization comes first, but we may still think about what comes next. Thanks for your Forresting efforts! -Bertrand
