Handbook writing Handbook?

[GreenSerpent]

So I heard you like handbooks...

Yeah! So, I'm busy starting collating information for a handbook and would like to know if there are any guides or handbooks on how to write a handbook. Failing that, some pointers/advice would be helpful.

Thanks!

[Psyren]

For myself, I find a couple of good ones that I like and leverage style elements from them. For example, color ratings, where and how to place pictures, what to spoiler and what not to spoiler etc.

Speaking of spoilers, one tip I can give is not to overuse them. They are great for organizing an involved section or increasing its readability, but they also make it so people have to click before they can control-F something that may be inside.

But yeah, though there are some common elements to most handbooks everyone tends to end up with their own unique style. I wouldn't worry about trying to "standardize" yours too much :smallsmile:

[ArcanistSupreme]

Regarding color coding, I would like to note that I strongly prefer that color coded words be bolded. To me,

Turquoise: A must have. Simply one of the best available options.
Blue: Very good. Any of these will be strong picks.
Green: Good in the right circumstances, but often situational. Be careful when selecting these.
Orange: Niche choice. Will either come up very rarely or be unimpressive when it does come up.
Red: Bad. Just don't take these.

is leaps and bounds more readable than

Turquoise: A must have. Simply one of the best available options.
Blue: Very good. Any of these will be strong picks.
Green: Good in the right circumstances, but often situational. Be careful when selecting these.
Orange: Niche choice. Will either come up very rarely or be unimpressive when it does come up.
Red: Bad. Just don't take these.


For myself, I find a couple of good ones that I like and leverage style elements from them. For example, color ratings, where and how to place pictures, what to spoiler and what not to spoiler etc.

Speaking of spoilers, one tip I can give is not to overuse them. They are great for organizing an involved section or increasing its readability, but they also make it so people have to click before they can control-F something that may be inside.

But yeah, though there are some common elements to most handbooks everyone tends to end up with their own unique style. I wouldn't worry about trying to "standardize" yours too much :smallsmile:

Psyren makes a lot of good points here. Here (http://www.giantitp.com/forums/showthread.php?t=233029) is a link to a compilation of existing PF handbooks. The magus handbook (http://www.d20pfsrd.com/extras/community-creations/-walter-s-lab/embedded-magus) and Saph's summoner handbook (http://www.giantitp.com/forums/showthread.php?t=184592) are a couple of my favorites. Take a look through those and identify not only what it is you like and what makes handbooks user-friendly, but also what inhibits readability and makes an otherwise well-researched handbook hard to use.

I agree that you shouldn't try to standardize handbooks, and given how different the classes are mechanically, I'd argue that it's almost impossible (for example, a druid handbook needs sections on spells, wildshaping, and animal companions, but a fighter handbook has no need for any of those).

On the subject of spoilering, I am going to agree that you shouldn't overuse them, but there are tricks that will allow you to use them and still maintain the utility of Ctrl+F. Clearly label each section and keep keywords outside of spoilers. Another trick is to add numerical tags to sections in the table of contents, and then keep the tag on the sections in the actual guide. For example:

I - Introduction
[1.1] - Class Overview
[1.2] - Color Coding
[1.3] - Role Overview

And then the headers will be "[1.1] Class Overview" and "[1.2] Color Coding" and so on. Then Ctrl+F can be used for "[1.1]" to go straight to the Class Overview section. By adding easily searchable tags, users can go straight to the section without hitting a common keyword such as "wildshaping" or "spells" fifty times on the way to the desired information. It can also allow a more judicious application of spoilering, which, if not overdone, is great for allowing readers to scroll rapidly through the guide.

An excellent example of tagging is this guide for Fallout: New Vegas (http://www.gamefaqs.com/xbox360/959557-fallout-new-vegas/faqs/61069). That guide is restricted entirely to MS Word formatting, but the basic idea can still be implemented, and some of the other formatting could also be used.

[GreenSerpent]

Oh aye. I was going to bold the colours anyway to make them stand out more.

[danzibr]

Totally going to fix up my handbook with some of these ideas.

[123456789blaaa]

There is a actually handbook for writing handbook written by prolific dnd guide writer Dictum Mortuum. Right now I can only find the version on the WOTC forums (http://community.wizards.com/go/thread/view/75882/19867186/Handbook_to_Guide_Writing)but I'm positive there's a more recent one. I've sent a pm to him asking about it.

[DementedFellow]

I suggest even if you use what others would consider as the established color code, please include the explanation of what the colors mean. I've come across plenty of handbooks that expects the reader to guess what the colors mean.

[ArcanistSupreme]

Color coding should also stick to a couple of simple rules if deviating from the more widespread color codes.

1. - Use colors that are distinct and easily differentiated
It should be obvious at a glance which options fall into which categories. Not all monitors are as good at separating colors, and not all people are as capable of distinguishing colors (I have trouble differentiating between certain shades of red and green). Blue, Black, and Red are great, but Indigo, Dark Slate Blue, and Navy are not.

2. - Try to keep it to three to five colors
Three to five is a good range of colors. Two colors is oversimplifying, and six or more is splitting hairs. If you get too many colors going, it also creates visual clutter and unnecessary distinctions. People coming to guides are often unfamiliar with a class entirely, and too many choices can overwhelm new players.

[Hecuba]

Tone & Style
A handbook is generally an informational (and sometimes technical) document target as an audience with lest mastery of a subject than you.
This makes many stylistic choices and figures of speech, such as sarcasm and litotes, counterproductive.
As a rule, keep the the tone positive-to-neutral and avoid most figurative language.

[ArcanistSupreme]

Tone & Style
A handbook is generally an informational (and sometimes technical) document target as an audience with lest mastery of a subject than you.
This makes many stylistic choices and figures of speech, such as sarcasm and litotes, counterproductive.
As a rule, keep the the tone positive-to-neutral and avoid most figurative language.

I disagree, and present Solo's Stupendously Superior Sorceror Strategems (http://brilliantgameologists.com/boards/index.php?topic=2180.0) as my argument. Granted, he does a good job of it, and using humor poorly could result in confusion and alienating your audience. I find many Cracked.com articles both hilarious and informative, but I agree that it is also very possible for the style to come into conflict with the content. In the end, it comes down to the author. If you think you can create a humorous piece that still contains all of the relevant information and is presented in an accessible way, go for it! If you don't think you can, don't!

Humor, like all of the tools presented here, can enhance and enrich a guide to make it a fun and engaging read. There are several guides that I enjoyed reading even though I never built or played the class in my life (see above sorcerer guide). Like any tool, it can be misused and become an obstacle for the reader, but there is nothing about the tool that is inherently bad. Just make sure you know how to use a tool before you pick it up.

[ericp65]

Tone & Style
A handbook is generally an informational (and sometimes technical) document target as an audience with lest mastery of a subject than you.
This makes many stylistic choices and figures of speech, such as sarcasm and litotes, counterproductive.
As a rule, keep the the tone positive-to-neutral and avoid most figurative language.

What are litotes?

[ArcanistSupreme]

What are litotes?

litotes (http://dictionary.reference.com/browse/litotes?s=t)
li·to·tes [lahy-tuh-teez, lit-uh-, lahy-toh-teez]
noun, plural li·to·tes. Rhetoric.
understatement, especially that in which an affirmative is expressed by the negative of its contrary, as in “not bad at all.”