There are various planning topics regarding user docs:
- Content
- Target Audience
- Modality
- Source format
- Delivery format
- Relationship with other forms of user support
- Licensing
Many of these are related, but not the same. Some content may work better in some formats (both source and delivery) than others.
CONTENT could be concepts, instructions, background information, reference information etc for the various fields of working with OO, like using, installing and deploying, administering, developing.
TARGET AUDIENCE could be
- end-users
- developer-users
- administrator-users
MODALITY could be user guides (a term for multi-topic, typically book-length documents) and a range of shorter document types: how-tos, tutorials, FAQs, and so on. For details on plans for various types of content, see the pages linked below:
- User Guides > multi-topic, typically book-length documents
- How Tos > short documents giving concise instructions for a specific task
- Tutorials > longer documents describing more complex tasks than How tos
- FAQs > collection of short Q/A pairs that target very specific problems
- Application help (or "online" help) > set of html/xml pages that come with the application and can be accessed context-sensitively directly from the application
There are other types to be thought of (like development cookbooks, reference sheets etc) but probably not at this stage.
SOURCE FORMAT could be ODT or wiki/other. The source documents for the existing guides (Getting Started with OOo and guides for Writer, Calc, Impress, Draw, and Math) will remain in ODT. Other guides (Developers, Programmers, Administrators) and other end-user docs (FAQs, etc) to be decided. See the user guides page for more details.
One approach would be to use a common source format for all documents to be maintained "internally" (i.e. not through the ODTAuthors framework and process) to limit the number of processes and formats and to allow repurposing of existing content. DITA was mentioned as possible format. This would, however, limit the usefulness of the wiki as collaborative tool. Q: Would there be a way to actually use the wiki as source and distribute to the various routes from there?
DELIVERY FORMAT could be ODT, PDF, printed, ePub, HTML, blog, wiki, video, etc. For electronic formats, target hardware could include laptop or desktop computers, iPads, Android tablets, smartphones, Kindles, etc. Except for the video/screencast format that would require an entirely separate production process, most of the output formats would be producible from one single source using different production templates.
Each choice, and combination of content/source/delivery choices, has pros and cons. We certainly don't have the resources (people or, in some cases, tools and/or skills) to produce a full range of content types or deliver in all possible formats, but we could have a "wish list" as well as a plan for what we are going to do over the next 6-12 months.
RELATIONSHIP WITH OTHER FORMS OF USER SUPPORT: This page summarises some recent discussion on this topic.
LICENSING: All official project user documentation should be under the Apache license. However, the existing user guides are not, and tracking down all the contributors to get agreement to change the license would be difficult if not impossible, and there is no guarantee that all would agree. We have a record of who contributed to each chapter (on the copyright page) but not who did what within the chapter. Therefore it may be necessary to completely replace the existing user guides or reconsider whether they are needed as part of an overall user documentation/user support strategy. See this page for a more detailed discussion.