Re: documentation additions and issue tracking (Was: App vs Data)

[Ferdinand Soethe <sa...@soethe.net>]

As you might know Ross and I have put considerable time into working
on a chapter structure for a book on Single Source Publishing with
Forrest. Since we didn't follow through with the project (there will
only be a German book) we are prepared to donate this structure (more
precisely: the rights to this concept for an English publication) as a
basis for the Forrest documentation project.

It might need some adjustments of course, but it was designed to
introduce people with basic skills to Forrest so it seems compatible
with what Addi had in mind.

If people think this is helpful, I'd check the OpenOffice file with
the concept into the issue tracker so that people can study it and add
their comments and suggestions (preferably as a modified
OpenOffice-document). Or is OpenOffice too proprietary to work with?

Once we have finalized the chapter structure, we could create it as a
new tab on Forrest main site with each chapter becoming a menu item
pointing to a page with a short abstract for this chapter (not being
written yet) and instructions on what to do if person wants to write
and contribute this chapter.

All open chapters could also become items in the issue tracker but I
think that having them in a structured menu helps recognizing at what
point in the documentation this chapter is placed and what its
purpose is.

I'm in favour of not writing a whole lot of basic documentation as
FAQs and standalone documents because the unstructured web of docs
created that way is much harder to comprehend (getting lost in the
web) and also a pain to maintain in the long run.

--
Ferdinand Soethe

Re: documentation additions and issue tracking (Was: App vs Data)

[David Crossley <cr...@apache.org>]

Sorry that email popped out before i had finished it ...

David Crossley wrote:
> Ferdinand Soethe wrote:
> > As you might know Ross and I have put considerable time into working
> > on a chapter structure for a book on Single Source Publishing with
> > Forrest. Since we didn't follow through with the project (there will
> > only be a German book) we are prepared to donate this structure (more
> > precisely: the rights to this concept for an English publication) as a
> > basis for the Forrest documentation project.
> 
> Not sure what your mean by "rights to this concept". See the Apache License 2.0

and your Contributor License Agreement CLA
http://www.apache.org/licenses/

--David

Re: documentation additions and issue tracking (Was: App vs Data)

[David Crossley <cr...@apache.org>]

Actually Ferdinand, this discussion should be happening on the dev list.

We reserve the user list for questions an assistance. Development discussions
can get quite busy and touch many different topics. We don't want to frighten
new users away with that.

--David

Re: documentation additions and issue tracking (Was: App vs Data)

[David Crossley <cr...@apache.org>]

Ferdinand Soethe wrote:
> As you might know Ross and I have put considerable time into working
> on a chapter structure for a book on Single Source Publishing with
> Forrest. Since we didn't follow through with the project (there will
> only be a German book) we are prepared to donate this structure (more
> precisely: the rights to this concept for an English publication) as a
> basis for the Forrest documentation project.

Not sure what your mean by "rights to this concept". See the Apache License 2.0

> It might need some adjustments of course, but it was designed to
> introduce people with basic skills to Forrest so it seems compatible
> with what Addi had in mind.
> 
> If people think this is helpful, I'd check the OpenOffice file with
> the concept into the issue tracker so that people can study it and add
> their comments and suggestions (preferably as a modified
> OpenOffice-document). Or is OpenOffice too proprietary to work with?

We can sure study it, but we need comments to come back to this mailing list.
We can't have design discussions shut away in separate documents.

Anyway, we have got to see what you are talking about first. I don't
really understand the three paragraphs below yet.

It would help to present a high-level overview to this mailing list.

--David

> Once we have finalized the chapter structure, we could create it as a
> new tab on Forrest main site with each chapter becoming a menu item
> pointing to a page with a short abstract for this chapter (not being
> written yet) and instructions on what to do if person wants to write
> and contribute this chapter.
>
> All open chapters could also become items in the issue tracker but I
> think that having them in a structured menu helps recognizing at what
> point in the documentation this chapter is placed and what its
> purpose is.
> 
> I'm in favour of not writing a whole lot of basic documentation as
> FAQs and standalone documents because the unstructured web of docs
> created that way is much harder to comprehend (getting lost in the
> web) and also a pain to maintain in the long run.
> 
> --
> Ferdinand Soethe