forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ferdinand Soethe <samm...@soethe.net>
Subject Re: documentation additions and issue tracking (Was: App vs Data) [moved from user list]
Date Thu, 02 Jun 2005 09:58:18 GMT

Ross Gardler wrote:

> I am thoroughly confused by the discussion and can only
> assume that it is a potential issue with the German publishers.

Correct.

> What Ferdinand is proposing to donate to Forrest is just the outline of
> a book. About half of this book is of no interest to a documentation
> effort within Forrest and I doubt we, as a community would develop those
> chapters, we would rip them out as not relevant (e.g. history of 
> WYSIWYG, why WYSIWYG is no good for many jobs, alternatives to WYSIWYG,
> XML basics, XSLT basics that kind of thing).

> If we strip out all these chapters what is left is an outline for a few
> chapters documenting how to work with Forrest. I stress *outline* there
> is nothing, in my opinion, of any intellectual value in this document,
> only a structure for a set of documentation files for Forrest. In other
> words, something that, if we were to look back through our archives,
> would have existed *before* the chapter outlines were written.

So it might be easiest to just take a fresh start and
assemble the outline from scratch rather than spending more time on
this discussion or research.

> In my opinion what should happen is that the relevant chapter outline
> should be ripped out of the proposal and put into SVN as XHTML documents 
> that we can point to via an URL to SVN. With our recent influx of offers 
> for help on beginner documentation this would provide a starting 
> framework for work to begin.

Fine by me.

My second proposal was to take that finished outline and create
menuitems on the Forrest Website for it (under a new "Manual" tab).

which means add something like this to site

<forrestmanual href=.... tab="Forrest Manual">
  <installForrest href=..../>
  <compileForrest href=..../>
  ...
  <ForrestPlugins href=....>
    <PluginConcept href=....>
    <InputPlugins href=....>
    ...
  </ForrestPlugins>
  ...
</forrestmanual>

The hrefs would be pointing to either

- finished pages or - pages that have just the abstract of that
  chapter (written during outline-design) and explain that this chapter
  still needs someone to write it and instructions on how to do that.

The goal is to give potential contributors some guidance on what is
missing what that chapter is all about and how their contribution
would fit into the finished manual.
  
--
Ferdinand Soethe


Mime
View raw message