bannerd

A. Introduction

B. Institutional Requirements

C. Project Software Requirements

D. Topics

E. Tools, References, and Terms

F. SPAN
(NASA Only)
Notes on needed updates

Content updates needed on this page: 

SWEHBDOC Basic Style Guide

1. Introduction

The SWEHB was constructed using the NPR 7150.2 as a foundation. Being a Handbook, it takes each of the Requirement from the NPR and expands on it to provide a "next level" of guidance to the user to satisfy the requirement. In Version C content from NASA-STD-8739.8 was added and the Handbook was expanded to more fully include Software Assurance activities.  

The content of the SWEHB Style Guide is divided into the following main areas, 

1.1 Overall Look and Feel

The Look and Feel of the SWEHB is the main focus of this page. It covers: 

  • Look and Feel of the general elements of the SWEHB page -
    • 2.1.1 - Header,
    • 2.1.2 Footer and
    • 2.1.3 Layout of the page body. 
  • 3.2 Page Top Messages - used for quickly putting a message on all pages of a given type. 
  • 3.3 Top Level Pages - these are the main pages for Requirements, Topics and other high level collections of information
    • 4. Requirement Pages - Layout for Requirements pages
    • 5. Topic Pages - Layout for Topic pages
  • 6. PAT Page Style
  • 7. Activity View Style
  • 8. Other Pages

1.2 Features and Tools

SWEHBDOC Features And Tools
The Features and Tools pages contain detailed instructions on implementing the Confluence features and using the tools, such as User Macros,  associated with the SWEHB. 

The SWEHBDOC Features And Tools page contains details on: 

  • 2. How References are managed on SWEHB pages. - SWEHBDOC References in SWEHB
  • 3. How the Activity View gives users an alternative, phase based, view of content.
  • 4. How the SWE History feature was built and implemented.
  • 5. PATs - Process Asset Templates and how they are used - 
  • 6. User Macros and how they are developed and used. 
  • 7. How Terms and Glossary lists are managed. 
  • 8. Editor Tools and Tips
    • Branch and Merge Process
    • Keyboard shortcuts
    • Powertools for SWEHB
    • Templates used in SWEHB
    • Redirect Tool
    • Managing Hyperlinks - shortcuts to adding relative links in a space
    • Table Cell Color Palette
    • Tabs in SWEHB Pages - This covers the "tabsetup" macro and how to use it. 
  • 9. How Blogs are managed.
  • 10. How to implement Sticky Headers in tables. 
  • 11. How to manage Crosslinking across pages in the SWEHB
  • 12. Usage of the Include Macro

1.3 Maintenance Of SWEHB

The SWEHBDOC Maintenance page contains details on: 

  • 2. Daily Healthcheck - a series of checks performed on SWEHB daily to verify its readiness and identify problems. 
  • 3. Document Archive - a description of how certain documents are stored, and divided to allow reuse in SWEHB pages. 
  • 4. Change History - a running log of major changes to SWEHB by year. 
  • 5. Development Area - a description of how the "Development Area" is used in each SWEHB Version
  • 6. PageTree - a description of the Hierarchy of a SWEHB Version and how to use drag and drop to reorganize the hierarchy. 
  • 7. Release Process - a description of how content releases are managed in SWEHB. 
  • 8. Consistency - a description of how consistency of language and terms is managed in SWEHB. 
  • 9. Refined Theme - a description of how the Refined Theme product is used to manage Header and Footer information across Versions. 
  • 10. New Version - a description of how a new version of the SWEHB can be built from an existing version. 


2. Look And Feel Of SWEHB

The Look and Feel of the SWEHB is implemented in two ways. The page Header / Footer, and the page layout implemented with the tab structure. 

See SWEHBDOC Refined Themes for details on how the header and footer are administered using the Refined Theme Plugin. 

As you read the sections below, also look at the page Header and Footer areas on this page.

2.1.1 Header 

At the top of each page is the Header. This area contains several elements that help the SWEHB user to navigate through the handbook. Follow along on this page to see the elements discussed below: 

  • Top left corner, link to  "Return to Software Engineering Community of Practice" is helpful to users that got to the SWEHB from the NEN and want to get back there. 
  • SWEHB Graphic - this is also a link back to the Introduction page (Home page for the SWEHB). The graphic is developed in a PPT file that is attached to the Book A. Introduction page. The name of the PowerPoint file is "SWEHB Multiver Graphics.pptx". It contains the current and several previous copies of the SWEHB Graphic (production and DREFT versions). The image is different for each SWEHB Version and is a good way to tell which version you are in. 
  • Navigation buttons - This takes the user to the main Top Level Pages in the SWEHB. The SPAN button takes the user to NEN where the SPAN application is available. 
  • Search is a Confluence feature that allows the user to perform a key word search for any string in the SWEHB. 
  • The next row of icons includes: 
    • Breadcrumbs - this is a trail from the current page, through the hierarchy, to the home page and to the top of the hierarchy. 
    • Lock - indicator of whether the page is locked or open for all viewers
    • Analytics - not used
    • Edit - for Editors to open the page in the page editor
    • View inline comments - not used
    • Star - mark the page as a favorite
    • Eye - toggle page watch feature - send watcher an email when page is edited
    • ... - dropdown menu
    • Angled arrows - toggle full page view - without header and footer. 

2.1.2 Footer

At the bottom of each page is a set of links to the NASA Privacy Statement and email links to the Curator of the SWEHB. 

2.1.3 Page Layout

Each page that users see is structured in a tabular format. The tabs are built using the "tabsetup" User Macro. See SWEHBDOC Tabs In SWEHB Pages for details. 

All SWE pages are constructed with the same set of tabs. Topic pages may have a different tab structure but will always have a "Resources" tab. 

3. Top Level Pages

3.1 High Level Structure 

The structure discussed here is the logical structure. The logical structure is mimicked by the pagetree which has a few obvious differences to facilitate maintenance of a version.  

The structure of the SWEHB (links are to pages in SWEHBVD for reference) is: 

  • A series of Top Level Pages which organized as quick access buttons visible in the SWEHB Header. For details on coding these links in Refined Themes see SWEHBDOC Refined Themes. 
  • Each Top Level Page has a collection of child pages 
    • SWE Pages - each requirement has a page with material specific to the requirement. All requirements pages are formatted the same for consistency. 
    • Human Rated Requirements in SWEHB - Human Rated Requirements, HR-9999 series. 
    • Topics Pages  - each topic has a page with material specific to the topic. All topic pages are formatted in a similar manner but due to the nature of the topic, the tabs may differ. Each topic has a Resources tab for consistency. 
  • Administrative pages - are included in the pagetree but are not directly visible in the page SWEHB header. The most common pages are described below. Additional pages may be found in a version because of special needs of projects in that version. 
    • Activity View - pages related to the Activity View imitated in SWEHBVD
    • Page Sections- contains pages for maintenance use (like Healthcheck) and other utility pages that may get pulled into a page using the Include Page macro (like New in SWEHB). 
    • Label database -  Label Database related pages.
    • Protected Area - a place for storing pages that users should not have access to but are necessary for maintenance. 
    • References Table  - a report containing References Table.  
    • Tools Table - pages related to tools. 

3.2 Page Top Messages 

To facilitate getting important messages out to users quickly, a system of "Page Top Messages" has been created. The Page Top Messages page is under Page Sections in the SWEHBVD pagetree. It fully explains the details you will need to use these messages. 

For example, If you want to put a message at the top of all SWE pages, You would go to the 2D-SWE Page Message page and follow the directions in that page. You would come up with a message, put it into the designated place in the 2D-SWE Page Message page and save it. Then you would see your message on the 2D-SWE Page Message page as well as any SWE page you go to. It will appear on the SWE page because of an Excerpt-Include macro which is at the top of every SWE page. 

Each of the four page top message pages has a similar layout. You can tailor what you want to say in each of the four types of pages. When building new pages it is necessary to put an Excerpt-Include macro at the very top if the page should participate in this feature. 

3.3 Top Level Pages

Top Level Pages are used as navigation aids for users to find types of content in the SWEHB. They are all unique in their design and are discussed below. To follow the descriptions, you can open each in a new window as you go along. 

3.3.1 Book A. Introduction  

This is the home page for the version of the SWEHB that corresponds to a version of NPR 7150.2. Book A. Introduction. 

  • It has an Excerpt-Include macro at the top to display the contents of the excerpt from 2D-Intro Message page. 
  • The Set-Data macro points to the tab where the Resources are listed. 
  • The Include-Page for Blog Links puts the "New in SWEHB" link at the right border of the page. 
  • Tab 1, left column,  contains a NASA logo and a Welcome message to users of the Handbook and a list of the two documents upon which the Handbook is based. 
  • Tab 1, right column, contains a list of the five most recent Blog postings regarding the SWEHB. This was instituted in version "D" of the SWEHB. 
  • Tab 2 is an Introduction to the Handbook. It summarizes the types of information that can be found in the Handbook. 
  • Tab 3 is the Title Material for the Handbook including the Document History Log. 
  • Tab 4 is for the Resources and contains a list of references used in the Handbook
  • Tab 5 contains instructions and links for accessing other versions of the Handbook
  • Tab 6 contains the Title Material for the NASA-STD-8739.8B

3.3.2 - Requirements

There are two requirements pages in the current version of the Handbook:

The layout of these pages is similar and explained below: 

  • Both have an Excerpt-Include macro at the top to display the contents of the excerpt from 2D-Major Page Message page. 
  • Both have an Include-Page for Blog Links puts the "New in SWEHB" link at the right boarder of the page. 
  • Both have an HTML table containing information about the contents of the page
  • Both have an Include-Page to pull in the contents of the SWEs In Numeric Order page. 

The balance of the pages are devoted to groups of requirements. 

3.3.3 D. Topics

There is one D. Topics page. It has:

  • An Excerpt-Include for 2D-Major Page Message  - individual topics will have an Excerpt-Include link for the 2D-Topic Page Message. 
  • A Show-If with an Editors Only panel for notes among editors. 
  • An Include-Page for Blog Links puts the "New in SWEHB" link at the right boarder of the page. 
  • A table with a single cell describing Topic in general
  • A CSS Stylesheet used for seting the style of cells in the topics tables
  • A "tabsetup" macro dividing the page into tabs for: 
    • 7.xx Engineering Topics
    • 8.xx Assurance and Safety Topics
    • 9.xx Software Design Practices
    • 6.xx Programming Checklists
    • 5.xx Document Contents
  • Each tab is organized into two columns with each cell in a row containing: 
    • Topic Title as a link to the topic
    • Excerpt from the topic describing the content of the topic

3.5 E. Tools, Refs, Terms

The E. Tools, References, and Terms contains:

  • An Excerpt-Include for 2D-Major Page Message  - individual topics will have an Excerpt-Include link for the 2D-Topic Page Message. 
  • An Include-Page for Blog Links puts the "New in SWEHB" link at the right boarder of the page. 
  • An Info panel describing the list of links on the page. 

Each link goes to a specific page. Each page contains details on where the page comes from or is built from. 

  • Terms  - full list of terms within the handbook
  • Acronyms - a full list of Acronyms within the handbook
  • Tools Table - the tools table lists all tools that are linked to throughout the handbook
  • References Table - the list of all references within the handbook

3.6 Other Pages

3.6.1 - FAQ 

The FAQ - Engineering, Assurance, and Safety page is a compilation of Frequently Asked Questions about the SWEHB. It is maintained by the Page Editor and is organized in the following tabs: 

  • Engineering Questions
  • Software Assurance Questions
  • Safety Questions
  • Resources - References pointing the relevant documents. 

Each question and answer may have links to supporting SWEHB pages.  

3.6.2 - Blog

Blog entries are used in the Handbook as a quick method of announcing changes or new content to the Handbook user community. They appear in: 

Each Blog posting has a Title, a short description of the change, and an area that can be expanded for more details on the change. 

Full documentation on Blog posting in SWEHB can be seen in SWEHBDOC Blogs In SWEHB. 

4. SWE - Requirement Page Style

4.1 Page Title

The title of the SWE has two parts. For Example: "SWE-987 This Is the Title"

  • The SWE number is 7 characters long and the numeric portion is always a 3 digit number. This is necessary for the referencing to work properly. See SWEHBDOC References in SWEHB for details
  • The title portion is a text headline for the SWE telling the viewer what the SWE is all about. It is advisable to not use special characters if possible. Some special characters will result in unpredictable issues for the SQL Server Database. 

The 7 character prefix is used by the References macros. When the HR requirements were added the numbering was managed to always ensure a 7 character prefix in SWEREFs and elsewhere. 

The SWE number comes from the NPR. The number is assigned there. The SWEHB Maintainer must work with the NPR authors to ensure that numbering of SWEs is performed properly. 

Care should be taken when adding SWEs to not create duplicate SWE numbers. Also, if a SWE has been added and published in a SWEHB version, the topic for that SWE number is established. SWEs may be reused if the content of the SWE has not changed much. However, if it is very different, consider using a new SWE number. There is a very simple reason for this. When a new version of the SWEHB is created, a full copy of the latest version of the SWEHB is used as a model for the new version. All the SWEs from the old version are duplicated in the new version. All references to a SWE are reused. If a SWE number is reused with a total different title, there will be confusion created among the references for the SWE because the first 7 characters of the SWE title are used for tying a reference to a SWE. 

4.1.1 Creating a new SWE Page

In the directory tree for a SWEHB version space there is a page for "SWE Pages". This is the container for all active SWEs in the version. In the Protected Area, there is another container for "Retired SWEs". All possible SWEs, used or reserved so far, are found in one of these containers.  If you are creating a new SWE page, start by opening, in a new tab, a page from the SWE Pages container. 

  • Use the "Copy" comment on an that existing page to create a new page from the old page. This works best if the existing page and new SWE are similar in structure. Specifically, "Institutional Requirements" from chapter 2 in NPR 7150.2 have fewer tabs than Project Software Requirements" in chapters 3 through 5 of NPR 7150.2.  
  • Retitle the new page by removing the "Copy of" from the title, changing the SWE number, and replacing the title with the new title of the page. 
  • At this point, Save the new page. 
  • Verify that the new page appears in the page tree for the space, in the SWE Pages container. If there is a problem with the page title, fix it before moving on. 
  • Next, open the page for editing and cleanout the old content, saving structure for reuse in the new SWE: 
    • You will reuse the TABSETUP structure including tab titles, and heading structures. 
    • In 1. Requirement, copy from NPR 7150.2 the paragraph number and SWE text into the Excerpt macro. 
    • In 1.1 Notes, copy from NPR 7150.2 the Notes for the SWE
    • In 1.2 History, replace the link to the SWE History page with a new link to a new page for this SWE. 

4.2 Tabbed Presentation Of Content

The content of most pages in SWEHB uses the TABSETUP User Macro. This macro serves as a container and organizer of content in a tabbed format. You can use any existing SWE as a model for following along with the descriptions below. For details on "tabsetup" see 

 4.2.1 Configuring TABSETUP

After inserting the TABSETUP macro, edit the macro and enter the titles for each of the tabs. In SWEHB, tabs are numbered. It is best to keep the tab title short to reduce overflow across the page. See SWEHBDOC Tabs In SWEHB Pages for additional details. 

4.2.2 Configuring a DIV 

Each tab is implemented using a DIV macro. Each DIV is edited and contains only an ID parameter. The format of the ID parameter is "tabs-1", "tabs-2", etc. 

The first line in the body of a DIV should be the numbered the same as the tab title. The text style should be "Heading 1".  Subsequent subdivisions in the DIV may use styles like "Heading 2", "Heading 3", etc. to organize content. 

Further detail in using all macros is included in the various maintenance guides. 

4.2.3 Tips on tabsetup and DIVs

  1. It is best to organize the DIVs in numeric order so you don't get confused when adding deleting or changing the order of  the content. 
  2. If a DIV is missing an ID number, the content will appear below the tabsetup area when you are viewing the page. 
  3. Numbering the first line of each tab helps you keep the tabs and content matched up properly. 
  4. If you have two DIVs with the same ID parameter, the page will have content from both IDs in one tab. 

4.3 Organization of a SWE or HR page

Each requirement is organized the same way. Project Software Requirements have an extra tab (tab 7) for Software Assurance. If you are building a new page, the simplest thing to do is 

  1. Go to an existing page and use the Copy command to get a "Copy of ..." page built. 
    1. Don't copy attachments - you will be adding your own later as you need them. 
  2. The value of using the Copy command is that you will build the new page in the correct place in the pagetree automatically. 
  3. The Copy command will put you in the editor with the new page. 
    1. Change the title of the page with your new SWE number and title
    2. Save the page. 
  4. Once you have the new page saved it will have a new title and the content will be that of the page you copied from. 
    1. Make sure that the page looks correct. 
    2. Edit the page and do the following in each of the DIVs: 
      1. Review each of the DIVs, keeping the structures that make sense to keep. For example, in tab 1 keep all of the header 2 lines because you will need them in your new page. 
      2. Delete content that you will be replacing with content for your new page. 
      3. Edit the "tabsetup" if necessary - for a SWE you will probably not need to make any changes. 
      4. Save the page again and check to see that all the old content is gone and only the necessary structural elements remain. 
  5. Continue editing the page to add the content for the new page. 
    1. Each tab has unique elements. Some require creating new pages (like "Related" pages) create these pages as necessary and make sure they appear under the new requirement page in the pagetree. 
    2. Add attachments as necessary to the page. 
    3. Add references as necessary. 
    4. Add images as necessary to the page. Images should be stored as attachments to the page. 

4.4 Tabs In A Requirements Page

This describes the structure in a requirements page. Content unique to the requirement is organized the same way for each requirement page to make it easy for the user to find things. 

4.4.1 Requirement tab

 1. Requirement - contains an EXCERPT macro with the text of the requirement in it. This facilitates reusing the text of the requirement in other SWEHB pages (using the EXCERPT INCLUDE macro)

 1.1 Notes - contains the text of the "Notes" for the SWE taken directly from the NPR 7150.2.  If there is no Notes section, the text  "NPR 7150.2, NASA Software Engineering Requirements, does not include any notes for this requirement."

 1.2 History - Contains a link to the History page for the SWE. History pages are located in the SITE space. There is a page for each SWE. On each page is a table with the text of each SWE by NPR 7150.2 version SWE. Between each version of the SWE text is a row describing the differences between the SWEs. 

 1.3 Applicability Across Classes - contains a table displaying the content of the applicability of the SWE for each of the software classes. It is either Applicable or Not Applicable. Applicability is assigned in an appendix in the NPR 7150.2. Applicability is only included for SWEs that appear in the matrix in the appendix of the NPR 7150.2. See SWEHBDOC - User Macros in SWEHB for details on using the Applicability macro. 

1.4 Related Activities - contains a list of the Activities that the requirement belongs to. These links are stored in the "Related Activities" page for the Requirement. This will need to be created under a new requirement. 

 4.2.2 Rationale tab

 2. Rationale - short statement explaining why the SWE is a requirement. This expands on the requirement and notes from the prior tab. 

4.2.3 Guidance Tab

 3. Guidance  - explains how the requirement can be implemented. It may include:

  • examples of how to satisfy the requirement
  • links to references and other pages containing templates for use in satisfying the requirement
  • quotations that help explain how the requirement can be implemented. For a complete discussion of Quotations, see the SWEHBDOC Quotations in SWEHB page. 
  • Links to related pages in the SWEHB
  • An "Additional  Guidance" section including links to the "Related SWEs" and "Related SM" pages stored under the requirement in the pagetree. 
  • Images or other aids to explaining how the requirement can be implemented. 

4.2.4 Small Projects

 4. Small Projects - Guidance on how the requirement can be satisfied by small projects. In some cases, small projects may get a waiver for the requirement. 

4.2.5 Resources

5. Resources 

5.1 References - contains a macro / report of SWEREFS that are called out in the page. See SWEHBDOC References in SWEHB. 

    • A Show-If macro with a Panel titled "Visible to Editors Only" is used to hide some details of interest only to editors. This includes: 
      • A table for SWEREFs to be added or deleted
      • List of SWEREFs called out in the text, 
      • List of SWEREFs NOT called out in the text, 
      • List of child pages. This is a quick way of accessing the "Related" pages plus any other development pages. 

5.2 Tools - an include page describing the tools library. 

Other sections as necessary to list other resources such as PATs, etc.

4.2.6 Lessons Learned

6. Lessons Learned

6.1 NASA Lessons Learned - bulleted list of items from the NASA Lessons Learned Database. 

    • Lesson Title in bold. Lesson Number 9999:  567  Extract from the lesson. Extract taken which points up the lessons that is appropriate to the SWE or Topic of this page. Add a SWEREF pointing back to the reference for the lesson. 

6.2 Other Lessons Learned (add this category only if appropriate)

    • Lesson Title in bold. Lesson Number 9999:  567  Extract from the lesson. Extract taken which points up the lessons that is appropriate to the SWE or Topic of this page. Add a SWEREF pointing back to the reference for the lesson. 

4.2.7 Software Assurance

7. Software Assurance - includes am "excerpt-include" macro pointing to the requirement excerpt in tab 1. The requirement is repeated here to reinforce what SA is responsible for. 

7.1 Tasking for Software Assurance - includes tasking taken from the NASA-STD-8739.8B that is relevant to the requirement. 

7.2 Software Assurance Products - a list of the SA products that are expected to be created or updated as part of the requirement. 

Objective Evidence list of evidence items to be created or updated. 

7.3 Metrics - a list of metrics to be collected in the performance of the requirement. 

7.4 Guidance - Additional guidance, beyond that in tab 3, and focused specifically on what SA is responsible for. 

7.5 Additional Guidance - Lists of links from "Related SWEs" and "Related SM" pages. 

4.2.8 Objective Evidence

8. Objective Evidence - This came from the tab 7 content and has been made into its own tab. 

5. Topic Page Style

Topics have been included in SWEHB since the first version in 2011. They have been modified over the years to include: 

  • Engineering Topics - Engineering topics are all found in under the Topics Pages in the page tree for the SWEHB version. Some older SWEHB versions have a slightly different mechanism for organizing the topics. All topics start with a four character number formatted "9.99". This allows the referencing macros to work properly. See SWEHBDOC References in SWEHB. Engineering topics are in the 7 series, like "7.99".  
  • Assurance and Safety Topics - Assurance and Safety topics are new in SWEHBVC. They are all found in under the Topics Pages in the page tree for the SWEHB version. Some older SWEHB versions have a slightly different mechanism for organizing the topics. All topics start with a four character number formatted "9.99". This allows the referencing macros to work properly. See SWEHBDOC References in SWEHB. Assurance and Safety topics are in the 8 series, like "8.99". 
  • Software Design Principles -  Software Design Principles are new in SWEHBVC. They are all found in under the Topics Pages in the page tree for the SWEHB version. Some older SWEHB versions have a slightly different mechanism for organizing the topics. All Principles do not have a special numbering in the title. This requires a different numbering scheme to use the referencing reporting to work properly. See SWEHBDOC References in SWEHB. 
  • Programming Checklists - Engineering topics are all found in under the Topics Pages in the page tree for the SWEHB version. Some older SWEHB versions have a slightly different mechanism for organizing the topics.  All topics start with a four character number formatted "9.99". This allows the referencing macros to work properly. See SWEHBDOC References in SWEHB. Programming Checklists are in the 6 series, like "6.99". 
  • Document Contents - Document Contents topics are all found in under the Topics Pages in the page tree for the SWEHB version. Some older SWEHB versions have a slightly different mechanism for organizing the topics. All topics start with a four character number formatted "9.99". This allows the referencing macros to work properly. See SWEHBDOC References in SWEHB. Programming Checklists are in the 5 series, like "5.99". 
  • FAQ - Engineering, Assurance, and Safety - the Frequently Asked Questions page is located under the Page Sections page in the pagetree. 

Each version of SWEHB carries forward a complete set of topics. As modifications are made to topics, the modifications are made only to the most current set of topics. This ensures that old guidance, applicable to an old version of the SWEHB, is still available to the viewer and is not confused by new material not covered in an older version of NPR7150.2. 

5.1 Page Title

The title of a Topic has two parts. For Example: "7.10 This Is the Title"

  • The Topic number is 4 characters long and is a single digit followed by a decimal point, followed by 2 digits. This is necessary for the referencing to work properly. See SWEHBDOC References in SWEHB for details
  • The title portion is a text headline for the Topic describing the subject of the topic. It is advisable to not use special characters if possible. Some special characters will result in unpredictable issues for the SQL Server Database. 

The 4 character prefix is used by the References macros.  

5.1.1 Topic Numbers

There are several numbering groups currently in use. If the new topic fits in one of these groups, you may assign the next number in the sequence to the topic. If you need to start a new group, there will be some additional steps below to accommodate this. 

  • 7.xx - Engineering Topics
  • 8.xx - Assurance and Safety Topics
  • 9.xx Software Design Principles
  • 6.xx Programming Checklists
  • 5.xx Document Contents

5.1.1 Creating a new Topic Page

In the directory tree for a SWEHB version space there is a page for "Topics Pages". This is the container for all active Topics in the version. In the Protected Area, there is another container for "Retired Topics". All possible Topics, used or reserved so far, are found in one of these containers.  If you are creating a new Topic page, start by opening, in a new tab, a page from the Topics Pages  container. This will ensure that the new page is properly located in the pagetree. 

  • Use the "Copy" comment on an that existing page to create a new page from the old page. This works best if the existing page and new Topic have a similar number of tabs.    
  • Retitle the new page by removing the "Copy of" from the title, changing the Topic number, and replacing the title with the new title of the page. 
  • At this point, Save the new page. 
  • Verify that the new page appears in the pagetree for the space, in the "Topics Pages" container. If there is a problem with the page title, fix it before moving on. 
  • Next, open the page for editing and cleanout the old content, saving structure for reuse in the new topic. 
    • Leave the "Excerpt-Include" macro for the "2D-Topic Page Message" in place
    • Leave the "Show-If" macro and it's contents in place. 
      • Clean out the expand macro 
    • Leave the Set-Data macro in place
    • You will reuse the TABSETUP structure including some tab titles, and heading structures. 

5.2 Tabbed Presentation Of Content

The content of most pages in SWEHB uses the TABSETUP User Macro. This macro serves as a container and organizer of content in a tabbed format. You can use any existing Topic as a model for following along with the descriptions below. 

 5.2.1 Configuring TABSETUP

Edit the "tabsetup" macro and enter the titles for each of the tabs. In SWEHB, tabs are numbered. It is best to keep the tab title short to reduce overflow across the page. See SWEHBDOC Tabs In SWEHB Pages for additional details. 

5.2.2 Configuring a DIV 

Each tab is implemented using a DIV macro. Each DIV is edited and contains only an ID parameter. The format of the ID parameter is "tabs-1", "tabs-2", etc. These numbers correspond to the tab numbers. 

The first line in the body of a DIV should be the numbered the same as the tab title. The text style should be "Heading 1".  Subsequent subdivisions in the DIV may use styles like "Heading 2", "Heading 3", etc. to organize content. 

Further detail in using all macros is included in the various maintenance guides. 

5.2.3 Tips on tabsetup and DIVs

  1. It is best to organize the DIVs in numeric order so you don't get confused when adding deleting or changing the order of  the content. 
  2. If a DIV is missing an ID number, the content will appear below the tabsetup area when you are viewing the page. 
  3. Numbering the first line of each tab helps you keep the tabs and content matched up properly. 
  4. If you have two DIVs with the same ID parameter, the page will have content from both IDs in one tab. 

5.3 Organization of a Topic Page

Each topic is organized in a similar way. For a new topic you will need to buildout the tabs and DIVs for the content. 

  1. Make sure that the page looks correct. 
  2. Edit the page and do the following in each of the DIVs: 
    1. For each DIV, add content for that tab of the topic.  
    2. Delete content that you will be replacing with content for your new page. 
    3. Edit the "tabsetup" if necessary - for a topic you will probably make many changes. 
    4. If you need more DIVs, you can add them at any time. Just be sure to:
      1. Number them appropriately.
      2. Edit the "tabsetup" to name the new tab. 
    5. Save the page again and check to see that all the old content is gone and only the necessary structural elements remain. 
  3. Continue editing the page to add the content for the new page. 
    1. Each tab has unique elements. Some require creating new pages (like "Related" pages) create these pages as necessary and make sure they appear under the new requirement page in the pagetree. 
    2. Add attachments as necessary to the page. 
    3. Add references as necessary. 
    4. Add images as necessary to the page. Images should be stored as attachments to the page. 

5.4 Tabs In A Topic Page

This describes the structure in a requirements page. Content unique to the requirement is organized the same way for each requirement page to make it easy for the user to find things. See SWEHBDOC Tabs In SWEHB Pages for additional details. 

5.4.1 Introduction of Purpose Tab

This is the first tab in a topic. It contains an overview of the subject matter in the topic. It gives the reader a high level view of what is contained in the other tabs. 

 5.4.2 Content Tabs

There can be as many content tabs as you need to present the material in the topic. Use them to organize the material in a logical fashion. 4.2.3 Guidance Tab

 3. Guidance  - explains how the requirement can be implemented. It may include:

  • examples of how to satisfy the requirement
  • links to references and other pages containing templates for use in satisfying the requirement
  • quotations that help explain how the requirement can be implemented. For a complete discussion of Quotations, see the SWEHBDOC Quotations in SWEHB page. 
  • Links to related pages in the SWEHB
  • An "Additional  Guidance" section including links to the "Related SWEs" and "Related SM" pages stored under the requirement in the pagetree. 
  • Images or other aids to explaining how the requirement can be implemented. 

5.4.3 Resources Tab

The resources tab is where the references are listed and other supporting materials are organized. The typical headers are: 

5. Resources 

5.1 References - contains a macro / report of SWEREFS that are called out in the page. See SWEHBDOC References in SWEHB. 

    • A Show-If macro with a Panel titled "Visible to Editors Only" is used to hide some details of interest only to editors. This includes: 
      • A table for SWEREFs to be added or deleted
      • List of SWEREFs called out in the text, 
      • List of SWEREFs NOT called out in the text, 
      • List of child pages. This is a quick way of accessing the "Related" pages plus any other development pages. 

5.2 Tools - an include page describing the tools library. 

5.3 Additional Guidance - contains a table of the contents of the "Related SWEs" and "Related SM" pages. 

5.4 Center Process Asset Libraries - contains a list of SPAN pages related to the subject of the topic. 

5.5 Related Activities - contains a list of Activities in the Activities View that pertain to the topic. 

5.4.4 Lessons Learned

This is a n optional tab that should be added only if there are applicable Lessons Learned from either NASA, a Center, or another source, for the topic. 

6. Lessons Learned

6.1 NASA Lessons Learned - bulleted list of items from the NASA Lessons Learned Database. 

    • Lesson Title in bold. Lesson Number 9999:  567  Extract from the lesson. Extract taken which points up the lessons that is appropriate to the SWE or Topic of this page. Add a SWEREF pointing back to the reference for the lesson. 

6.2 Other Lessons Learned (add this category only if appropriate)

    • Lesson Title in bold. Lesson Number 9999:  567  Extract from the lesson. Extract taken which points up the lessons that is appropriate to the SWE or Topic of this page. Add a SWEREF pointing back to the reference for the lesson. 


6. PAT Page Style

Process Asset Templates are a natural evolution of guidance in SWEs and Topics. They typically start out as checklists, process step lists, document content structures, or other content and evolve into templates that can be used in project activities or as prototypes to be modified, tailored, and improved before being used in a project.

Process Asset Templates is a general category of pages. These pages include: 

  • Checklists - preformatted checklists to be used in some activity. Can be modified to suit a project's unique needs. 
  • Process Lists - lists of things that may be done in some specified order. Can be modified to suit a project's unique needs. 

A PAT is numbered so that existing code in templates and macros for references and tools can be reused. The PAT number series will be included in the first 7 characters of the page title. This code is used in PAT reports, and the PAT Database.

For full details on PATs see SWEHBDOC PAT - Process Asset Templates In SWEHB.  

7. Activity Page Style

Handbook content has been organized into Activities. Activities represent the major groupings of work performed in Software Development Life Cycle phases. They are useful for the work in all Life Cycles including Waterfall, Agile, or other life cycles.  The details of this view are in the A.00 Activity View page. There is a Gliffy diagram of the view with links to the appropriate activity phase pages. Links are also provided in a bulleted list. 

Activity View was first rolled out in 2025, in SWEHBVD of the Handbook. It organizes and presents the SWEs and Topics in the SWEHB in a two ways: 

  • By Development Phase - This is for all content that is part of a phase in the Software Life Cycle. 
  • By Organizational Structure - This is for Software Assurance and Institutional content that is distributed throughout the Life Cycle or is supportive of the Life Cycle. 

7.1 Activity Page Organization

Large Activities, like Software Life Cycle Planning, have multiple tabs. Smaller activities fewer tabs. Each activity is divided into two sections: 

  • Overview - provides a high level description of what types of content is in the Activity. 
    • Includes a description of the Frequency that the activity is performed. 
  • Related Content - provides details and links to other Handbook pages
    • Related SWEs
    • Related Work Products
    • Related Process Asset Templates
    • Related Topics
    • Related SPAN Links

7.2 Maintaining Activity Pages

The pages are designed to be simple to maintain. They are just bulleted links to pages with excerpts from those pages displayed. 

The real work in maintaining the activities comes when changes are made to SWEs, Topics, PAT pages. Frequently a change in a page triggers a change in other pages. 

  • Adding a PAT to a SWE page requires
    • a link in the SWE page pointing to the PAT. 
    • a link in the corresponding Activity page Pointing to the PAT and the SWE

This builds a multidirectional cross-referencing among pages. In the activity View there is a list of detail pages which can be used to help maintain the Activity Pages. These have much more detail collected from the "Related" pages attached to each SWE and Topic page in the Handbook. 

The pages with two levels of numbering (such as "A.01.01 Planning the Work") include: 

  • Organization Table listing - this is used to built the Activity Page
    • Titling for the activity
    • Link list of SWEs
    • Link List of Work Products
    • Link list of Process Asset Templates
    • Link List of Topics
    • Link List of SPAN pages
    • Link List of Activity Pages
  • Analysis Table - this table is built from the links in the Organization Table. It pulls data from the appropriate SWE and Topic pages and displays the Related Links for those pages. Any Related link should be considered for adding to the Activity and the Organization Table. 
    • SWE or Topic
    • Related SWEs
    • Related SM
    • Related Activity

8.  Frequently Asked Questions - FAQ

The FAQ pages are a collection of Frequently Asked Questions that apply to: 

  • Engineering
  • Software Assurance
  • Safety
  • All Disciplines - General questions

 Questions are listed on the appropriate tab with the Answer immediately below. References that are provided point to the Resources tab and a References List like any SWE of Topic page. 

The page is organized into tabs and the General Questions are included at the bottom of all tabs (using an Include Page macro). See FAQ - Common Frequently Asked Questions for Engr, SA, Safety. 

The link to the FAQ Page appears in the page top information on the D. Topics page.  


  • No labels
Page Editor: Tim Crumbley
NASA Official: Tim Crumbley
Accessibility
NASA Software Engineering Handbook - A service of the NASA Office of the Chief Engineer
NASA Privacy Statement
______________________________________________________________________________