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. 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. 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. 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) 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. 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. 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. 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. 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. 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: 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. 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. When a Panel is used for a quotation, two features of the Panel macro are implemented: There are additional features employed in a Quotation. See Quotations in SWEHB for a full description. When a Panel is used for a list of Process Asset Templates, two features of the Panel macro are implemented: There are additional features employed in a PAT List. See Process Asset Templates for a full description. 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. 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.
See edit history of this section
Post feedback on this section
1. Introduction
1.1 Writing Style
1.2 Headings and Sub-headings
1.3 Content Balance
2. Consistency of Language
2.1 Choice Of Words In the SWEHB
3. White Space and Lists
3.1 White Space
3.2 Lists
3.2.1 - Bulleted List
3.2.2 - Numbered List
3.3 Images
4. Panels, Notes and Warnings
4.1 Panel Macro
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
Content Style and Consistency
Web Resources
View this section on the websiteUnknown macro: {page-info}
Panel Macro Used For A Quotation
Panel Macro Used For A List of Process Asset Templates