bannerd

A. Introduction

B. Institutional Requirements

C. Project Software Requirements

D. Topics

E. Tools, References, and Terms

F. SPAN
(NASA Only)

Versions Compared

Old Version 20

changes.mady.by.user Haigh, Fred

Saved on

compared with

New Version Current

changes.mady.by.user Haigh, Fred

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Panel
borderColorred
titleNotes on needed updates
Expand

Content updates needed on this page: 

  1. tab 12 - needs more content
11

8. Tools

The pages listed below provide details on the tools available in SWEHB. 

Tabsetup
12. Excerpt and Include Macros01. Introduction
12. References
23. Activity ViewSWE History
34. SWE HistoryUser Macros
45. PATsTerms
56. User MacrosTools
67. TermsBlog
78. ToolsSticky Headers
89. BlogCrosslinking
910. Sticky Headers
1011. Crosslinking
Excerpt and Include Macros
Div
idtabs-1

1. Introduction

Excerpt

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: 

Children Display
depth2

Div
idtabs-2

2. References

SWEHBDOC References in SWEHB  explains how references are used and maintained in SWEHB. 

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. 

4. 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.  

1.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. 

1.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. 

1.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. 

2. 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. 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. 

4. 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
idtabs-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. 

Div
idtabs-4
RevSWE 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 BReworded 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 PlansSWEHBVC:SWE-003 - Center Improvement Plans
nopaneltrue
Difference between C and D

No change

D
Excerpt Include
SWEHBVD:SWE-003 - Center Improvement PlansSWEHBVD:SWE-003 - Center Improvement Plans
nopaneltrue
Div
idtabs-5

5. PATs - Process Asset Templates

See SWEHBDOC PAT - Process Asset Templates In SWEHB for full details on PATs. 

Div
idtabs-6

6. 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
    pageHTML 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: 
    Children Display
    pageMarkup Macros
  • There is a longer list of macros that are not used in any SWEHB space. These are listed in SWEHBDOC - User Macros in SWEHB. 

6.1 Critical User Macros

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. 

6.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. 

6.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. 

6.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. 

6.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. 

6.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
idtabs-7

7. 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. 

7.1 Terms Database

In SWEHBVD, Terms Database is a static list of terms defined in a variety of documents referenced in SWEHB. 

7.2 List of Terms

The List of Terms lives in the SITE space. In the SWEHBVD space there is a E. Tools, References, and Terms page with a Terms page below it in the pagetree. The Terms page has an Include-Page macro pulling the SITE: List of Terms page into it for display purposes.

Any editing of the List of Terms page should be done in the SITE space. 

Div
idtabs-8
Children Display
pageSWEHBDOC Editor Tools and Tips
excerptTypesimple

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. 


RevSWE 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 BReworded 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
nopaneltrue

Difference between C and D

No change

D

Excerpt Include
SWEHBVD:SWE-003 - Center Improvement Plans
SWEHBVD:SWE-003 - Center Improvement Plans
nopaneltrue

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
idtabs-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
    pageHTML 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: 
    Children Display
    pageMarkup Macros
  • There is a longer list of macros that are not used in any SWEHB space. These are listed in SWEHBDOC - User Macros in SWEHB. 

4.1 Critical User Macros

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
idtabs-5

5. 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. 

5.2 List of Terms

The List of Terms lives in the SITE space. In the SWEHBVD space there is a E. Tools, References, and Terms page with a Terms page below it in the pagetree. The Terms page has an Include-Page macro pulling the SITE: List of Terms page into it for display purposes.

Any editing of the List of Terms page should be done in the SITE space. 

Div
idtabs-6

6. Tools

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
pageSWEHBDOC Editor Tools and Tips
excerptTypesimple


Div
idtabs-7

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: 

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. 

Div
idtabs-8

8. Sticky Headers

Excerpt Include
SWEHBDOC Sticky Headers
SWEHBDOC Sticky Headers
nopaneltrue

Sticky headers was implemented in Topics 8.16 and 8.18 of SWEHBVD in June of 2024. 

It only work properly in tab 1 of a page where the "tabsetup" macro is used to present content in tabs. 

See SWEHBDOC Sticky Headers for details. 

Div
idtabs-9

9. Crosslinking

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. 

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: 

9.2 Page Information

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. 

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. 

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. 

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. 

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
borderColorblack
titleExample 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
idtabs-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, 

Image Added


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. 

Div
idtabs-9

9. 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. 

10. Sticky Headers

Sticky headers was implemented in Topics 8.16 and 8.18 of SWEHBVD in June of 2024. 

It only work properly in tab 1 of a page where the "tabsetup" macro is used to present content in tabs. 

See SWEHBDOC Sticky Headers for details. 

11. Crosslinking

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.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: 

11.2 Page Information

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.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.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.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.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. 

Additional guidance related to this requirement may be found in the following materials in this Handbook:

Div
idtabs-10
Excerpt Include
SWEHBDOC Sticky HeadersSWEHBDOC Sticky Headers
nopaneltrue
Div
idtabs-11
Panel
borderColorblack
titleExample of a "Related Links" table from SWE-121
Related Links
Include Page
SWEHBVD:SWE-121 - Related SWEsSWEHBVD:SWE-121 - Related SWEs
Include Page
SWEHBVD:SWE-121 - Related SMSWEHBVD:SWE-121 - Related SM
Div
idtabs-12

12. Include and Excerpt Macro Usage

There are two Confluence Macros that are used extensively in SWEHB. These are the Include-Page and Excerpt Macros. Some of the usages are described below. 

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. 

12.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. 

12.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. 

12.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. 

12.2 Include Page in Various SWEHB Pages

12.3 Excerpt-Include in Pages

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
______________________________________________________________________________