OK, I generally agree with most of the comments, except the there should be at least a paragraph of explanation of "What is OOo? Meaning, at least some, as Janet says, "Marketing" fluff...a paragraph (or two) can be used to steer a curious reader to the appendices (or encourage them to read on).
The problem with using appendices is that I tried (believe it or not) to keep the text short. As appendices the text may need more work (embellishment) to make it worthwhile reading...which is something we need to give ourselves more of? I could do it, but I would like to produce a "simple" Calc chapter first. This is the current structure of the document...any suggestions? What is OpenOffice.org? 1 What exactly is “Open Source”? 2 How is OpenOffice.org licensed? 3 The advantages of OpenOffice.org 4 What does OpenOffice.org include? 5 Component packages 5 How does OpenOffice.org compare? 8 Standard features 8 New features in version 2 10 Minimum Requirements 13 Getting the Software 13 End user Support 14 Frequently Asked Questions ***BTW I used "exactly" in the title of the section "What exactly is “Open Source”?" to mean this is not a "brief" (1 or 2 sentence) overview...but should not be a thesis either. Though it may be superfluous. Daniel, could you go ahead and review the entire chapter, that way I can work it over as a whole. And I would appreciate more continuing feedback from others on this chapter...I am hesitant to make drastic changes to the document based on one reviewer, regardless of who they are. It surely is tough dancing between technical and informational... On Mon, 2005-02-28 at 14:34 -0600, Janet M. Swisher wrote: > 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 > -- Regards, Rick Barnes www.nostabo.net ******************************************************************* PRIVILEGED - PRIVATE AND CONFIDENTIAL This electronic mail is solely for the use of the addressee and may contain information which is confidential or privileged. If you receive this electronic mail in error, please delete it from your system immediately and notify the sender by electronic mail or using any of the contact details noted herein. This e-mail sent via Evolution 2.0.3 running on a Linux 2.6.10 kernel.
signature.asc
Description: This is a digitally signed message part
