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 tabs in this page are come from the introductions to each of the features and tools. The full details come from the pages listed below:
Any document, NASA document or external document, that is referred to in a SWEHB page should be treated as reference.
Most references are called out specifically in the content of a page and include a document ID or title and a link to the Resources tab where a link to the reference can be found. Some references may not be directly called out in the text of the SWE page. These are "implied references.
Div
id
tabs-3
3.
Activity View
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.
In the A.00 Activity View page of SWEHBVD, there is a "Software Development Life Cycle" diagram with links to all the Activity pages in the view.
Each Activity page has one or more sections devoted to a phase of the Life Cycle. Some of the more complex phases have multiple tabs to group related content. The next level down contains:
Brief explanation of the work that is included.
Frequency of This Activity - statements of when the activity is initially performed and may need to be performed again.
Links to SWEHB pages - These are organized by:
Related SWEs - the requirements that are performed in this activity.
Related Work Products - the Work Products that are generated by satisfying the requirement.
Related Process Asset Templates - the PATs that are available to be used
Related Topics - this Supplementary Material provides additional guidance in support of the requirement.
Related SPAN Links - link(s) to SPAN pages with links to pages in Center Process Asset Libraries having helpful templates and content.
All pages in the SWEHB are reviewed and have links pointing to Related SWEs and Supplementary Materials which are listed in the Guidance tabs or Resources tabs. This cross-referencing extends to Activities and provides Bi-directional traceability among the Activities, Requirements, and Supplementary Materials. See the Crosslinking Tab for more details.
SWE History
The SWE History page contains a complete history of the text of the SWE throughout it's history. It contains the actual text for each version of NPR7150.2 as well as a description of what changed between versions.
3.1 Structure of SWE History Pages in SITE Resources
See a page from the SWEs in Current Use for a complete picture of the structure.
The body of the page consists of two elements:
Excerpt - using the Excerpt macro, describe the last use of the SWE.
Table of SWE texts with differences.
3.2 Last Use
The Excerpt contains a statement of the last use of the SWE. It is done in an excerpt macro so it is available to the "Children Display" of either the SWEs in Current Use page or the SWEs Retired page. Both of these pages are containers displaying the contents of the child pages beneath them.
There are only a few Last Use statements in current use:
Last used in rev NPR 7150.2D
Last used in rev NPR 7150.2C
Last used in rev NPR 7150.2B
Last used in rev NPR 7150.2A
Used first in NPR 7150.2D
Reserved in NPR 7150.2A
Reserved after NPR 7150.2B
Reserved SWEs are those never used in a published version of the SWEHB. They may be used as necessary without fear of causing problems with references.
3.3 Table of SWE Texts
The table below is an example from SWE-003 of a history table.
The header row is in green and contains the two column headers.
The Rev column is for
the Rev letter from the end of the NPR 7150.2 designation, or
The difference statement row
The Difference statement row is in blue and contains a brief statement of the changes between versions of the SWE text.
The version rows contain the version letter and the actual text of the SWE from that version of NPR 7150.2. Starting with Rev C, the text of the SWE is pulled in using an "Excerpt Include" macro from the SWE page in the appropriate SWEHB space. This ensures that the text is accurate everywhere it is used in the SWEHB.
Rev
SWE Statement
A
1.2.2 Each Center shall maintain, staff, and implement a plan to continually advance its in-house software engineering capability and monitor the software engineering capability of NASA's contractors, as per NASA's Software Engineering Initiative Improvement Plan.
Difference between A and B
Reworded and removed reference to NASA SEIIP.
B
2.1.3.2 Center Directors, or designees, shall maintain, staff, and implement a plan to continually advance the Center’s in-house software engineering capability and monitor the software engineering capability of NASA's contractors.
Difference between B and C
No change
C
Excerpt Include
SWEHBVC:SWE-003 - Center Improvement Plans
SWEHBVC:SWE-003 - Center Improvement Plans
nopanel
true
Difference between C and D
No change
D
Excerpt Include
SWEHBVD:SWE-003 - Center Improvement Plans
SWEHBVD:SWE-003 - Center Improvement Plans
nopanel
true
3.4 Adding SWE History Pages
It will be necessary to add a History page if a new SWE is added and there is no existing History page for it. The easiest way to add a new SWE History page is to:
Open the SWEs in Current Use page and then open one of the existing SWE History pages in a new tab.
In the History page you just opened, Initiate a "Copy" command from the menu options next to the Edit command.
The Copy command will offer to create the copy under the same page as the existing page. Hit "Copy" to approve this.
The new page will have "Copy of" in front of the title of the old page. Just remove the "Copy of" and put in the new SWE number. Save the page.
Verify that the page is added by refreshing the SWEs in Current Use page and seeing the new history page.
If you don't see the new page, fix this problem before continuing.
In the new SWE History page, perform the following cleanup:
Update the statement in the Excerpt macro to reflect the status of the SWE.
Remove old SWE Statements for versions that do not apply.
Add rows in the table to contain a new difference row and a new SWE statement row using the existing rows as a model.
Get the SWE statement using an Excerpt Include macro to retrieve the text from the SWE page in the appropriate version of the SWEHB.
3.5 Retiring SWEs
When retiring a SWE, it's history page should be edited appropriately to indicate that it is retired from the SWEHB.
The SWE History page for the retired SWE should then be moved from the SWEs in Current Use page to the SWEs Retired page. The easiest way to do this is using the drag and drop feature of the SITE space page tree. When you have moved the page, refresh both containers and make sure the history page has been moved.
3.6 SWE History in a SWE page
In tab 1 of each SWE there is a section "1.2 History". Below the header is an Expand macro with the title "Click here to view the history of this requirement:". The body of the Expand macro contains an Include-Page macro pointing to the appropriate History page in the SITE space. This will display the history of the SWE without having to exit the SWE page.
Div
id
tabs-4
4. User Macros and Templates
User Macros are a feature of Confluence. It allows users to build small macros in HTML code (formerly in Wiki Markup) to perform small tasks.
In older versions of Confluence, the macros were written in a markup language called Wiki Markup. This contained proprietary commends in Confluence that worked with plugins and other macros to add a lot of functionality to the product. In recent versions of Confluence, warnings have been added to this part of the admin console stating that existing macros in Markup code may, at some point, stop functioning. Users have had several years of grace period to convert their user macros to HTML.
The current status of User Macros in SWEHB is as follows:
Some macros have been converted to HTML. These are used on various pages in SWEHB. the code is documented in the pages below:
Children Display
page
HTML Macros
Some macros are no longer used. They are listed in Macros not used.
Some macros are in Markup language but are still usable. they are listed below:
The most critical User Macros from a SWEHB perspective are listed below. If Confluence or the associated plugins stop working, there are work-arounds for some of these.
4.1.1 References Macros
See SWEHBDOC References in SWEHB for details on how references work with Confluence and the Scaffolding and Reporting plugins. Tab 6 of that page describes a method of handling references in the absence of these plugins. It depends on using the Confluence Excerpt-Include Macro with the existing SWEREF pages. See also SWEHBDOC - Replacing Refstable Macros.
4.1.2 TABSETUP Macros
The "tabsetup" macro is described in several places in the SWEHBDOC. It is implemented in a User Macro written in Wiki Markup language. If it cannot be rewritten in HTML or if the Confluence code cannot support this macro, an alternative to the tab structure will be necessary to preserve the look and feel of the SSWEHB. SWEHBDOC - Eliminating the tabsetup Macro describes how to implement a tab-like structure using a nested page structure for SWEHB pages and links at the top of each page to mimic the tabs of the current "tabsetup" macro.
4.1.3 Applicable Macros
The Applicable Macros have evolved over the years. Since there are only a few combinations of Yes and No selections, the easiest way to replace these macros would be a set of images that display the "Yes / No" choices. Using a simple binary numbering system would yield a manageable number of images to embed in SWE pages needing them.
4.1.4 SWEREFN Macro
The purpose of the SWEREFN macro is to take the user to the "Resources" tab on a page. the body of the macro contains the 3 digit number for the SWEREF. The replacement for the macro would be
the 3 digit number in blue color and superscript formatting
Users would need to be retrained to go to the Resources tab/page to find the SWEREF number that would get them to a link to open the reference.
4.2 Templates
Templates are a Confluence feature that allow for the structuring of pages using the Confluence "live template". This builds variable fields into a page so that the scaffolding and reporting plugins can use these variables. See SWEHBDOC - Templates used in SWEHB for details.
Div
id
tabs-4
4. SWE History
Div
id
tabs-5
5.
Quotes
Div
id
tabs-6
6. User Macros
Terms
In the original SWEHB (space: 7150), there was a "term" macro in use. Terms were defined in a database structure using the reporting and scaffolding plugins. the "term" macro was put into SWEHB pages wherever a term was used. When the user hovered over the term, a Windows "tool-tip" popped up and contained a definition of the term from the term database.
After a number of updates to Confluence and the plug-ins, the term macro no longer worked as originally designed. The macro was removed from SWEHB pages in version SWEHBVB and the Terms Database was reduced to a static list of terms.
5.1 Terms Database
In SWEHBVD, Terms Database is a static list of terms defined in a variety of documents referenced in SWEHB.
The pages listed below provide details on the tools available in SWEHB. This tab is also the subject of the page SWEHBDOC Editor Tools and Tips.
Children Display
page
SWEHBDOC Editor Tools and Tips
excerptType
simple
Powertools
Div
id
tabs-97
9
7. 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:
Book A. Introduction in the right column of tab 1. The list includes the five most recent posts. This gives Handbook users a feel for how frequently the Handbook is being updated with new content.
All pages in the SWEHB are reviewed and have links pointing to Related SWEs and Supplementary Materials which are listed in the Guidance tabs or Resources tabs. This cross-referencing extends to Activities and provides Bi-directional traceability among the Activities, Requirements, and Supplementary Materials. See the Crosslinking Tab for more details.
11
9.1 General Crosslinking
The concept of Crosslinking comes from the application of Bi-directional Traceability. A requirement from NPR 7150.2 is a simple statement of something that must be done in a Software Development Project. When it is enhanced in the Handbook, information is added such as
Rationale - Why the requirement should be done i.e. what is the value to the project of performing the requirement.
Guidance - How to satisfy the requirement. This can include multiple ways to satisfy it, some of which might be complex.
Small Projects - Discussion on alternatives for how small projects might satisfy the requirement.
Resources - References and other helpful information about the requirement.
Lessons Learned - Information about problems that have occurred or were avoided by satisfying the requirement.
Software Assurance Guidance - How SA supports and assists in the satisfying of the requirement.
It is up to the author to identify the crosslinking that is appropriate on a page. This is based on the content. For example, in a SWE page Guidance tab there may be a statement about how a Topic provides a technique that can be used to satisfy the requirement. A link to the Topic page would be included in the text of the tab. It would be appropriate to also have a link in the Topic that points back to the SWE acknowledging that the topic can be used to satisfy the requirement. Additionally, Since all SWEs are a part of one or more Activities, it would be appropriate for the SWE to point to the appropriate Activity. From the point of view of the Activity, the Activity should include the SWE in its list of related SWEs and the Topic in its list of Related SM (Supplementary Materials).
To support this concept, each SWE, and Topic has several child pages. For example, SWE-020 - Software Classification would have the following children:
By reviewing the "Page Information" for a page it is possible to see the incoming and outgoing links for the page this will tell you:
Incoming Links - Other pages that are pointing to the page as s target. This is where other pages will send the user to the page.
Outgoing Links - Links to other pages that the page is sending users to.
Parent Page - the parent of the current page in the hierarchy
Each of the incoming and outgoing links should appear in one of the "Related" pages to be properly crosslinked.
11
9.3 Crosslinking in SWEs
A SWE page may have links to the following crosslinked pages:
Another SWE page that is in the same phase, in a preceding phase, or a succeeding phase.
SM page that is somehow related to the subject of the SWE or its guidance.
Activity where the SWE may be performed.
11
9.3 Crosslinking in Supplementary Materials
A Topic or SM page may have links to the following crosslinked pages:
SWE pages that are in the same phase, in a preceding phase, or a succeeding phase.
SM page that is somehow related to the subject of the Topic or its guidance.
Activity where the Topic may be used.
11
9.4 Crosslinking in Activities
An Activity page may have links to the following crosslinked pages:
SWE pages that are in the same phase, in a preceding phase, or a succeeding phase.
SM page that is somehow related to the subject of the SWE or its guidance.
11
9.5 Additional Guidance Sections
In each SWE there is an "Additional Guidance" section in tab 3 (and tab 7). This section contains a Related Links table with Include-page macros pulling in the "Related SWEs" and "Related SM" child pages.
In each Topic there is an "Additional Guidance" section in the Resources tab. This section contains a Related Links table with Include-page macros pulling in the "Related SWEs" and "Related SM" child pages.
Panel
borderColor
black
title
Example of a "Related Links" table from SWE-121
Additional guidance related to this requirement may be found in the following materials in this Handbook:
Related Links
Include Page
SWEHBVD:SWE-121 - Related SWEs
SWEHBVD:SWE-121 - Related SWEs
Include Page
SWEHBVD:SWE-121 - Related SM
SWEHBVD:SWE-121 - Related SM
Div
id
tabs-10
10. 'Excerpt" and "Include"Macro Usage
There are two Confluence Macros that are used extensively in SWEHB. These are the "Excerpt" and "Include-Page" Macros. Some of the usages are described below.
10.1 Excerpt in SWEHB Pages
The excerpt macro is used frequently to mark a selection in a page that can be easily used by other macros. The limitation of Excerpt is that you can have only one Excerpt macro in a page.
Excerpt has a single parameter which is a toggle for displaying the Excerpt on the page. In some cases you may not want the Excerpt displayed on it's page, it will be displayed when you use "Excerpt-Include" macro to display the Excerpt on a different page.
The "Excerpt-Include" macro takes one parameter - the page from which you get the Excerpt.
10.1.1 Excerpt in a SWE Page
The requirement in a SWE page, tab 1.1, is in an excerpt macro. This facilitates including the requirement in other locations such as:
In tab 7 of a Project Software Requirements page. The requirement is restated at the start of the tab so the user won't have to go back to tab 1 to read it.
In other pages where a requirement is restated for emphasis.
10.1.2 Excerpt in Other Pages
In non-SWE pages, the excerpt is used to give a thumbnail sketch of the subject matter in a page. The excerpt may then be called up in another macro like a "Children Display" macro with the "Excerpt Display" parameter set to "simple". This will display a list of pages, each with their excerpt displayed in a bullet format.
10.2 Excerpt-Include in Pages
Every topic page has an excerpt. The excerpt is displayed in the D. Topics page next to the page link that is it taken from. This helps users understand what the topic is about.
Notice that each topic page link has a short description next to it. This description comes from the Excerpt in the topic page. For example,
The link to 8.30 was created using the "[8.30 - Fli"command and then the correct topic / version was selected. In this case I am using SWEHBVD. Next I initiate an "Excerpt-Include" command starting with "{exc" and select Excerpt Include from the dropdown menu. When it asked me for the page to get the Excerpt from, I paste in the title for topic 8.30. Then I can view the preview the excerpt to be sure that there is one.
10.3 Include Page in Various SWEHB Pages
When there is a significant amount of content (usually a paragraph or more) that must be placed in multiple pages, the Include-Page macro is the best way to manage this. The content is placed in its own page and then can be "included" in another page using the "Include-Page macro.
Open this link in a new page to see all the places where include is used in SWEHB pages. For example, there is an Include-Page macro at the top of every page in the handbook to pull in content from the Page Top Message for the page.
