1. Introduction

1.1 Writing Style

The content of the SWEHB is intended for use by anyone developing software in NASA and subject to NPR 7150.2. The writing style should be simple and concise. The objective is to convey the most information in a way that is easily understood and clear. 

Complex structures and and convoluted content are to be avoided in programming and should be avoided in the SWEHB as well. The objective is to make things clear and helpful to all who read this material. 

1.2 Headings and Sub-headings

The SWEHB pages are typically tabbed. However, even un-tabbed page should follow this guidance. The heading styles available in Confluence allow for clearly dividing content into coherent pieces. The first heading used on a page or tab should be Heading Style 1. 

Heading Style 2 should be used next to separate the major areas of the page. 

Heading Style 3 should be used to further divide content under a Style 2 heading. 

If you find the need for using additional styles like 4, 5, or 6, consider reorganizing the content onto multiple tabs or pages. Once you get beyond style 3, the content is usually to complex to describe in a meaningful manner. You may find that further use of styles 4 and beyond makes the content very unbalanced. 

1.3 Content Balance

As you write your content, try to keep a sense of balance. If you find that most of the tabs or headings have only a small amount of content but one section keeps expanding into more and more levels of complexity, it's time to re-evaluate. Your reader needs to be able to easily follow your train of thought. If you make things too detailed in one area, you may lose the reader along the way. Also, the other sections that are more brief may not be regarded as important. Or, worse, the complex section may be the most important, but is impossible to follow. the content may even contain logic errors or incomplete pathways. In programming, this can lead to disasters. If content is unclear, it may not be followed correctly, leading to poor or no results. 

2. Consistency of Language

2.1 Choice Of Words In the SWEHB 

Many words and terms used in the SWEHB have multiple spellings. Alternatives creep into common usage and as content in the SWEHB is updated from other sources, these alternatives may get included in the SWEHB. They must be found and fixed during regular maintenance if they are not fixed at the time they are initially introduced. 

The table below includes a list of words and terms that need to be found and changed to the Preferred wordings. 

3. White Space and Lists  

3.1 White Space

White space is your friend. Some authors try to fill pages with content consisting of long sentences and huge paragraphs. When readers see this type of page, their eyes glaze over. Reading takes longer and comprehension drops. The author's points are lost in the noise of the page. 

White space is a simple way for an author to make the page more inviting to the reader. Part of this technique is to use shorter sentences. Each sentence should have a single point. If you have to make multiple points, consider other methods. 

3.2 Lists

When making multiple points, you may have started out using heading styles. That is good for dividing things at a high level. Down at the "working level" you may need some other ways to group related points. The Confluence editor gives us two basic ways of doing this - Bulleted List, and Numbered List. 

These lists typically generate a lot of white space on the right side of the page. This gives the reader the impression that you are using smaller phrases and sentences to make the content easier to read and understand.  

3.2.1 - Bulleted List

• This is an item in the bulleted list
• Each item is prefaced with a bullet at the left
• Each time you hit Enter at the end of a line, you get another bullet
  • If you hit the Tab key you indent to a new sub level of the list
  • You can have several items at this level
  • you can get back to the previous level using two consecutive Enters
• If you had hit one more Enter you would have been jumped out of the bulleted list

When using the bulleted list in the Confluence editor, you have no control over the type of bullet you get. If you need to change the type of bullet, you may need to use HTML. 

3.2.2 - Numbered List

The numbered list will give you numbers instead of bullets. These lists may be used in places where you need to indicate a sequence of steps or a priority of things. 

1. This is an item in the numbered list
2. Each item is prefaced with an integer at the left
3. The integer includes the point after it
4. Each time you hit Enter at the end of a line, you get another numbered line
   1. If you hit the Tab key you indent to a new sub level of the list
   2. Notice that the "numbering" has changed to lettering
   3. This change is automatic 
   4. You can have several items at this level
   5. you can get back to the previous level using two consecutive Enters
5. If you had hit one more Enter you would have been jumped out of the bulleted list

3.3 Images

Images are another way to present content and manage white space on the page. The old adage "A picture is worth a thousand words." applies here. 

The image below is taken from a page in the SWEHBVD. The screenshot was captured using the Snipping Tool in Windows. It was then saved as a PNG file and attached to this page. It is inserted here and formatted as follows: 

• Size: 600px - this may be changed to make the text readable and control the overall feel of the page. Thumbnails are not used frequently in SWEHB
• Border On - to emphasize the limits of the image
• Centered - to leave white space on both the right and left of the image (balance).

4. Panels, Notes and Warnings

Panels are another technique for using white space. It uses a border to divide the page into discrete areas Each area is separate from the rest of the page. Each of these areas has a specific point to be made and emphasized. 

4.1 Panel Macro

Alternatives to the plain Panel macro are easy to achieve, however. The alternatives being used, starting with SWEHBVD, are shown below. 

4.1.1 Panel Macro Used For A Quotation

4.1.2 Panel Macro Used For A List of Process Asset Templates

4.2 Note Macro

4.3 Warning Macro