Hi Rick, Daniel, Jean, and whoever else,
I agree with Jean that this is a difficult type of chapter to write, because it straddles between technical writing and marketing writing, both of which are challenging to do well. This chapter may well be a user's first point of contact with OOo documentation, and therefore, I think that the main questions that users are likely to bring to this chapter are:
* What does this product do? * Why should I use it?
I suggest taking a journalistic "inverted pyramid" approach: Give all the relevant facts at a very high level of detail first, then delve into progressively lower levels of detail later on. That way, a "lazy" (or busy or rushed) reader will get the main gist, even if they don't read the whole thing. For example, I think a bullet list of the major components should appear somewhere on the first page of the main text, to answer the first question. Readers have an unfortunate tendency to ignore tables-of-contents, and might not keep looking all the way to page 5 to get that information. They might instead conclude "This document doesn't answer my questions", and start looking around for a more promising document.
Note that questions like "How was this product developed?" and "How is this product licensed?" are not among the first questions that users have. That information is part of the very detailed answer to "Why should I use it?", but users won't begin to understand the relevance unless they have the high-level answers: "It's free and not controlled by one powerful company, and you can still share files with others." The day when they care about the detailed history and licensing information is not likely to be the day when they first look at downloading the product --- it will be much later, if ever.
I've observed that a regular, though not frequent, question on the [email protected] list is something like "Can my organization(/company/agency) distribute this product to all our users?" So there definitely are people who need the concept of open source software explained to them. But I think most individual users who don't know about OSS also don't care, and don't need to know about it in order to get up and running with the software.
Therefore, I agree with the suggestion to move that information to appendices, where the interested reader can find it. I agree that the material is very informative, and not easily gleaned from other sources. I think the 10% of users who do need that information (I just made that number up) will find it, read it, and get value from it, even if it is in an appendix. But as an appendix, it won't interfere with the other ~90% of readers achieving their goals.
Regards, Janet
-- Janet Swisher --- Senior Technical Writer Enthought, Inc. http://www.enthought.com
