Metasploit/StyleGuide

The Metasploit Book Writing Guide

When using screen shots please keep them "clean" and non-promotional. Tech writers tend to insert screen shots of their company's web site or their research groups banner. Try to keep all screen shots boring and generic for the sake of consistency.

When using screen shots try to use light backgrounds with dark text for all screen shots. It's not quite as leet looking but it uses much less ink if someone decides to print out the content.

When using any graphics keep in mind that light colors will not print well. Avoid using yellow on a white background and try not to color-code screen elements when a description or other icon will suffice. If you talk about how the green button does one thing and the rest does another the reader will be very confused when they print in black and white. Some readers are color blind and would not understand these references either.

A screen shot is not a replacement for a thorough explanation but there is no need to describe every element of a screen shot.

Write as if you are working with the reader in real-life. Use "we" to represent yourself and the reader. For example "Now that the buffer has been created we can use this method to insert our return address". Do not use "we" to represent yourself and the co-authors.

Always use present tense and active voice. For example write "Use the ENCODER option to specify a particular payload encoder" do not write "The ENCODER option is used to specify a particular payload encoder"

Avoid slang and curse-words. Some users aren't as cool as you and may not understand. Worse they may be offended.

Avoid long words and sentences. If you are using more than 3 commas in a sentence think about a shorter way to represent the same idea. Try to keep paragraphs short. Over two sentences but no more than half a page long each.