IT SOLUTIONS
Your full service technology partner! 
-Collapse +Expand
Tech Writer
Search Tech Writer Group:

Advanced
-Collapse +Expand Tech Writer Store

Prestwood eMagazine

March Edition
Subscribe now! It's Free!
Enter your email:

   ► KBRole-Based T...Technical Wr...Publishing   Print This     
Next Random Article Next Random Tidbit || Change Topic Random From All
  From the January 2016 Issue of Prestwood eMag
 
Tech Writer Publishing:
Prestwood Online Style Guide
 
Posted 9 years ago on 12/16/2008
Take Away: Use up to four levels within articles (Heading 1..4). Within text, bold language elements and menu options. Use italics to bring attention to non-code things such as companies, important words, etc. Use bold+Italic for embedded topics and follow with a colon. Use the paragraph style for text and preformatted for code. Max width for images is 700 pixels.

KB101711



Introduction

Every publisher I've published with has a different style guide. The first publisher I worked with on a professional level was Sams Publishing. I happily dug into their style guide and followed it as closely as possible. After all, I was now writing at a professional level! When I published with others, learning their style guide was a hardship. It felt like a waste of time. The style guide differences among Sams Publishing to Borland Press, CorelPress, Osborne, and McGraw/Hill seemed random to me. With that said, you do not have to follow our online style guide to post content to the Prestwood Programmer Community (PPC). However, if you wish to fit-in a bit better, this post will help. We kept our online style guide simple with as few guidelines as reasonable.

Style Guides

The following items comprise our online style guide:

Suggested Heading Levels

We only use four levels of headings: Heading 1, Heading 2, Heading 3, and Heading 4.

For example:

Heading 1

Text Body

Heading 2

Text Body

Heading 3

Text Body

Heading 4

Text Body

Text Body

Bold Code and Italicize Important Words: Use the paragraph style for text. Within a text body, bold code elements and menu options and use italics to bring attention to non-code things such as companies, important words, definitions, etc. Optionally, you can italicize important words only the first time they are used.

Example 1 (bold and italic usage):

The Prism language is not a strongly typed language like Delphi for Win32. Prism supports type inference where you just use a variable and the compiler will then choose the lowest type possible (such as an Integer before a LongInt). With Prism, you frequently do not have to use commands to convert from one type to another.

Example 2 (avoiding quotes):

Instead of...

The rules for code blocks within a language dictate where you can declare variables, how you "bracket" code, etc.

It is better to use...

The rules for code blocks within a language dictate where you can declare variables, how you bracket code, etc. 

Definitions

Definitions are important words or phrases and you should italicize them but only the first time they are used.

Code Blocks

Use the preformatted style for code. Use two spaces in place of each tab. Use Heading 4 if you include an introductory sentence fragment.

Rich Text Code Blocks

You can format the code with colors and bold but it isn't necessary and is sometimes difficult to maintain. I like to color important code blue and warning or error code red (preferably embedded in a comment). Also, I sometimes make comments dark gray. I find this combination draws the readers attention to the important or interesting code.

Sample Code Listing:

Pre, .PRE 
{
/* Do not use percentages with font sizes. */
/* font-size:86.5%; */


font-size:.8em;

font-family:Consolas,Courier New,Courier,monospace;
Margin:0 0 0 0;
Padding:0px 1px 0px 4px;
color:#444444;
background-color:#DDDDDD;
border-left:3px #BBBBBB solid;
}

 

Embedded Introductory Title: Tips, Notes, Bullets, etc.

An embedded introductory title is a title at the beginning of a paragraph. We suggest using bold+Italic followed with a colon. Optionally, indent once Used in KB post 101711. The only time we normally use bold+italics is for the introductory word for notes, tips, etc. 

Examples:

Note: This is an example of an indented note. To indent or not is your choice based on context.

Tip: This is a sample tip.

This following is a non-tip/non-note example:

Built-In: Some development tools have a reporting tool built-in and some do not. For example, typically desktop databases such as Paradox and Access have a built-in reporting tool and typically that reporting tool is used with nearly every application built with it. A built-in reporting tool makes development of reports across many clients and applications consistent and therefore easy.

Add-On: Development tools that do not have a built-in reporting tool need to use either a currently bundled report writer, or one of the popular reporting tools that integrates well with the development tool. For example, popular reporting tools include Crystal Reports, ReportBuilder, and MS SQL Reporting Services (tied to MS SQL).

Here is an example of a bulleted list with embedded introductory titles:

  • Private: Used by the defining class only. Invisible outside of the class except by friendly classes.
  • Protected: Used by the defining class and descendant classes only (plus friendly classes).
  • Public: Visible wherever its class can be referenced.

Images

Use images as frequently as reasonable. Images bring a post alive. Recommended max width for images is 700 pixels.

Avoid <HR>

In general, avoid <hr> tags as they add visually distracting lines.

Conclusion

Remember, you do not have to abide 100% to our online style guide. Our suggested guidelines are for those contributers who wish to save our editors time. If you have questions or suggestions, please add a comment below.


Comments

0 Comments.
Share a thought or comment...
 
Write a Comment...
...
Sign in...

If you are a member, Sign In. Or, you can Create a Free account now.


Anonymous Post (text-only, no HTML):

Enter your name and security key.

Your Name:
Security key = P1257A1
Enter key:
KB Post Contributed By Mike Prestwood:

Mike Prestwood is a drummer, an author, and creator of the PrestwoodBoards online community. He is the President & CEO of Prestwood IT Solutions. Prestwood IT provides Coding, Website, and Computer Tech services. Mike has authored 6 computer books and over 1,200 articles. As a drummer, he maintains play-drums.com and has authored 3 drum books. If you have a project you wish to discuss with Mike, you can send him a private message through his PrestwoodBoards home page or call him 9AM to 4PM PST at 916-726-5675 x205.

Visit Profile

 KB Article #101711 Counter
12014
Since 12/16/2008
-
   Contact Us!
 
Have a question? Need our services? Contact us now.
--Mike Prestwood

Call: 916-726-5675

email: info@prestwood.com


Go ahead!   Use Us! Call: 916-726-5675 


©1995-2017 Prestwood IT Solutions.   [Security & Privacy]