bannerd

Content Style and Consistency

 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. 

Variants

Preferred/Corrected Word(s)

Consistency Check Complete?

life cycle, lifecycle, life-cycle

life cycle


safety critical, safety-critical

safety-critical


non-conformance, nonconformance

non-conformance


top level, top-level

top-level


flowed-down, flowed down

Flow down


Software Assurance Plan, SA Plan, SAP

Ask Tim


NPR 2810.1 Security of Information Technology

NPR 2810.1 Security of Information and Information Systems


NIST SP 800-40 Creating a Patch and Vulnerability Management Program

NIST SP 800-40  Guide to Enterprise Patch Management Planning: Preventive Maintenance for Technology


IEEE Standard Measures of the Software Aspects of Dependability, 8 November 2005

IEEE Standard Dictionary of Measures of the Software Aspects of Dependability, 8 November 2005


CMMI-Dev 2.0, CMMI-Dev 1.3

CMMI-Dev 2.0 (for current version of Handbook only)


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

Numbered lists can be tricky. This is especially noticeable when you try to add content in the middle of the list or if the list is a mixture of numbers and bullets. Keep it simple to avoid digging a deep hole that you can't get out of. 

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

Simple Panel macro is discouraged in most SWEHB pages starting with SWEHBVD. The grey frame is too hard to see and can lead to confusion. 

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

Panel Macro Used For A Quotation

When a Panel is used for a quotation, two features of the Panel macro are implemented: 

  • Title - A title is used to make the reason for the panel clear
  • Border Color - A border color of "blue" is used to denote that the panel contains a quotation from another source. 

There are additional features employed in a Quotation. See Quotations in SWEHB for a full description. 

4.1.2 Panel Macro Used For A List of Process Asset Templates

Panel Macro Used For A List of Process Asset Templates

When a Panel is used for a list of Process Asset Templates, two features of the Panel macro are implemented: 

  • Title - A title is used to make describe the PATs in the list
  • Border Color - A border color of "green" is used to denote that the panel contains a list of PATs 

There are additional features employed in a PAT List. See Process Asset Templates for a full description. 

4.2 Note Macro

The Note macro is used for calling special attention to some statement in the SWEHB. 

The general use of the Note macro is without using the Title feature. In special cases, the Title may be used to add even more emphasis to a note. 

The Note Icon is typically left "checked" (the default) to call attention to the note. Additionally, the note has a yellow border and pale yellow background to further make it stand out on the page. 

4.3 Warning Macro

The Warning macro is used for calling special attention to some statement in the SWEHB. it is rarely used but may be used in cases where special increased attention is drawn to some content. 

The general use of the Warning macro is without using the Title feature. In special cases, the Title may be used to add even more emphasis to a warning. 

The Warning Icon is typically left "checked" (the default) to call attention to the warning. Additionally, the warning has a red border and pale red background to further make it stand out on the page. 

  • No labels