Guidelines for writing tutorials

These guidelines are for writing tutorials so they will fit in with the existing user guides. You are also welcome to submit tutorials (or links to them) that do not fit these guidelines.

These guidelines are for writing tutorials to be provided in ODT and PDF. You are also welcome to submit tutorials in other forms, including wiki format, HTML, and video (e.g., YouTube).

General approach

1. Use the style names given in the OOoAuthors User Guide chapter template. OK to change style definitions (page size, font style & size, etc) for a specific range of docs, but please keep the same style *names* for compatibility if info is reused in other documents.
2. All contributed work should be under the same licenses as User Guides (CC-BY & GPL3), again for resuse purposes.
3. Docs should be focused on specific tasks, although some docs might be explanatory overviews with x-refs to how-to type docs. For example, the main tasks involved in producing a thesis are x, y, z, etc., which are explained in detail in documents X, Y, Z.
4. Docs should explain what you are trying to do, and why you might want to do it, not just how to do it.
5. Docs should contain lots of tips and hints that address common problems or misunderstandings, or just better ways to do something. The most obvious method often isn't the best or most efficient. Also, some choices can have unwanted -- or at least unexpected -- consequences.
6. Suggest around 20-40 pages max; some topics could be as short as 4 pages.
7. Include lots of screenshots, appropriately cropped and labelled. Capture screens using a fairly neutral window theme (look in current UGs for examples), not dark or bright colors.
8. In any procedure, explain *one* way to do something, not several alternatives.
9. Focus on *good practice* in explanations. For example, explain how to use *styles* instead of manual formatting.

Before you begin

1. Let's not duplicate info in the user guides if/when that info covers the topic in a similar way. However, many topics in the UGs are fairly general, covering a range of possibilities, and often NOT explaining when and why one might want to do whatever is described.
2. Let's not duplicate existing information, e.g. other tutorials or how-to's. Do some research before proposing or starting a tutorial, to see if something similar has already been written.
3. OOoAuthors has a Writer's Guide and a Style Guide as well as templates. The more closely new docs follow these guidelines, the better they will fit into the overall documentation set. At this point, let's not reinvent the wheel, even though a better wheel might be available.