1. Introduction

The Software Engineering Handbook (SWEHB) web site was started in 2010. It was built on a Confluence Wiki platform by Jon Verville from GSFC. There were a number of plugins and macro packages used to built out the rich capability in the product. It was initially an internal to NASA site. 

It was anticipated that revisions to the NPR7150.2 would be used to update the SWEHB and that only one version, in space 7150, based on the most current NPR, would exist. In 2017 the second version of SWEHB was born. It was based on NPR7150.2B in the space SWEHBVB. In 2018 work began on a third version of the SWEHB in space SWEHBVC. The most current version is based on NPR7150.2D and is in space SWEHBVD. 

The architecture of the SWEHB sites is discussed on this page. It includes the basic Confluence Platform, add-on software like plugins and macro bundles, and a small amount of user (NASA) written macros that give the SWEHB its look and feel. 

Additional documentation including Style Guides for certain types of pages are included as pages under this page. 

• Activity View in SWEHBVD — The Activity View of SWEHB is based on the Software Development Life Cycle
• Branch and Merge Process — The Branch and Merge Process is used for Large scale changes to pages in SWEHB. 
  • SWE-876 - Programming Code
• Deconstructing Confluence
• Editors Tips and Tools
  • Keyboard Shortcuts
  • Managing Hyperlinks
  • SAWG Meeting Q
  • Table Cell Color Palette
• Other SWEHB Content
  • Blogs In SWEHB — Blogs in SWEHB were added in February, 2023. They started out as a way to introduce major changes in SWEHB to the user community. 
  • Sticky Headers
    • 8.16 - SA Products - Testing Large table in tab 1 —  Provides information for the major software assurance and safety work products resulting from the performance of the Software Assurance and Software Safety (SASS) tasks required in the NASA Software Assurance and Software Safety Standard, NASA-STD-8739.8.  Each product’s section may include sub-products, potential analysis methods/technologies, and suggested content for capturing and reporting on the product activities.
    • 8.18 - SA Suggested Metrics - Table with no macros
    • 8.18 - SA Suggested Metrics - Testing Large table in tab 1 — This topic contains the complete list of software assurance/safety metrics that are suggested for use with the SA tasks in NASA-STD-8739.8.
• SWEHB Style Guide — Style Guide for SWEHB Versions. 
  • Content Style and Consistency — Content writing style and consistency notes. 
  • Macros not used — This page contains User Macros that are not used in any space. 
  • Process Asset Templates
    • Add a New Pat
    • Configuring an Asset as a PAT
      • Managing Attachments
        • Add or Update a PAT on a SWE or Other Page
        • Updating a PAT
    • Initial Implementation of PATs
  • Quotations in SWEHB — Quotations structure and maintenance are described here. 
  • References in SWEHB — Explains how references are used and maintained in SWEHB. 
  • SWEHB Maintenance Guide — Maintenance Guide for SWEHB Versions. 
  • Templates used in SWEHB
    • Template - pat — reference is a template for defining the parameters of a PAT page
    • Template - reference — reference is a template for defining the parameters of a SWEREF page
  • User Macros in SWEHB — Macros used in SWEHB spaces
    • HTML Macros
      • applicable-b — HTML - SWE Applicability by Software Class  Used in SWEHBVB
      • applicable-c — HTML - SWE Applicability by Software Class  Used in SWEHBVC and SWEHBVD
      • applicable-sa — HTML - SWE Applicability by Software Class  Used in SAEHB 
      • floatbox — HTML - Provide floating box for setting apart quotations from other text
      • ifnotzero — HTML - Used in other macros to detect if a parameter is not zero
      • ifzero — HTML - Used in other macros to detect if a parameter is zero
      • small — HTML - used in macros to change font size  
      • swerefn — HTML - Provides a superscript code for referring to a reference - link takes the user to Resources tab
      • tablink2 — HTML - redirect user to a specific tab in a tabsetup  
    • Macros no longer used
      • scroll-only — Not used: formerly was used in ref report code 
      • sectionheader — No longer used - was used in development 
    • Markup Macros
      • applicable — Markup - SWE Applicability by Software Class  Used in 7150 
      • pattable-topic — Markup - PAT table of assets used in topic pages - not used 
      • refstable — Markup - Builds a list of references from the references database for SWE pages
      • refstable-intro — Markup - Builds a list of references from the references database for the A. Introduction page
      • refstable-topic — Markup - Builds a list of references from the references database for Topic pages
      • tabsetup — Markup - Divide pages into a set of tabs 
      • toolstable — Markup - Builds a statement about tools in SWE page. No code, just text. Could replace with a page to include. 
      • toolstable-topic — Markup - Builds a statement about tools in Topic page. No code, just text. Could replace with a page to include. 
• SWEHB Style Guide - content pieces — The Style Guide defines the look and feel of the SWEHB.  
• SWE Style Guide and Template — Style guide for SWEs. May be used as a template. 
  • Lessons Learned Formatting in SWEs
  • SWE History Maintenance — Maintenance guide for SWEs History pages.  
  • SWE Maintenance Guide — Maintenance guide for SWEs.  
• Topic Style Guide — Style guide for Topics. May be used as a template. 
  • Topic Maintenance Guide — Maintenance Guide for Topic pages. 
• User Macro Maintenance
  • Changes Related to Scroll Macros
  • User Macro Code Archive
    • UM-applicable-b — The "applicable-b" macro is used in SWEHBVB space to visually display the applicability of the SWE based on Class. 

 1.1 User Access

Access to the SWEHB is granted to anyone who can get to it through the NASA network as well as anyone on the world wide web through the URL: SWEHB.NASA.GOV. It is not necessary to log in to Confluence to use the SWEHB. Users may browse the content as Anonymous users. This access to content allows users to view content and download attachments. Editing and content creation is restricted to a small number of developers and curators who have Confluence logins and are in the appropriate group of editors. 

 2. Platform

The SWEHB uses the Wiki from Atlassian Software. This Wiki is Confluence. It is simple to use but made more powerful with the addition of plugins and macro software. 

Originally, SWEHB was deployed in GSFC on version 2.x of Confluence. By 2017 the SWEHB had been moved from GSFC to MSFC. Over the years the platform was upgraded many times by Atlassian. The system was upgraded to version 7.4.4 on Nov 20, 2020. 

Currently, the platform is on virtual servers at MSFC and maintained by the IT organization there. 

2.1 - Server

• Confluence runs on a JAVA virtual server. 
• Operating System is Unix. 
• Application Server is Apache Tomcat. 

2.2 - SQL Server

Confluence stores content in a My SQL database. All content is stored in database records using a KEY to identify what space the content belongs to. This means that multiple spaces can be stored in the same database. See tab 5 for a list of current spaces and their KEYs. 

2.3 - Confluence 

Initially, Confluence 2.x was used to develop the SWEHB in 2010. Subsequently the version of Confluence was updated to the current 7.x. 

 3. Plugins and Macros

Plugins and Macro Bundles give the Wiki additional capabilities beyond what comes with Confluence. The plugins and Macro Bundles currently in use in the SWEHB. 

 3.1 Scaffolding

This plugin allows for identifying variables and storing values for the variables in Confluence pages. Once the values are embedded in the page, they can be used by other plugins and macros to enhance the value of the content.

For example, in SWEHB, data on references is collected and stored in SWEREF pages: 

• Link - URL for the reference
• Title - Title of the referenced document
• Citation - additional information about the reference such as, author, publisher, dates of publication, etc. 
• Notes - other descriptive information of interest
• Affiliated SWE - internal page references within the SWEHB where the reference is called out

Scaffolding macros and their usage (12/15/2021)

• live-template (1843)
• set-data (185)
• hidden-data (65)
• text-data (15)
• table-data (9)
• list-data (6)
• list-option (4)
• content-options (4)
• attachment-options (1)
• number-data (1)

 3.2 Reporting

This plugin uses data collected in the Scaffolding plugin and stored in pages. The reporting plugin allows the developer to select values, sort data, and build reports to display the selected data in a meaningful way for the viewer. 

For example, in SWEHB, the References section of SWE pages contains a report listing of references mentioned in the page, or having an obvious relationship to the page. 

Reporting macros and their usage (12/15/2021)

• content-reporter (263)
• text-filter (244)
• report-info (223)
• report-empty (215)
• report-list (188)
• report-body (170)
• text-sort (147)
• report-link (135)
• report-block (92)
• number-filter (75)
• report-column (65)
• report-eval (65)
• report-table (65)
• local-reporter (26)
• date-sort (14)
• report-on (8)
• space-reporter (3)
• report-variable (3)
• date-filter (3)
• expanding-reporter (2)
• content-filter (2)
• report-image (1)
• repeat-filter (1)
• grouping-reporter (1)
• natural-sort (1)
• user-reporter (1)
• user-filter (1)

 3.3 Gliffy

Graphic image editor. Has the ability to embed links in images. 

3.4 Adaptivist Replace and Render - ?

3.5 Angular JS Integration for AUI - ?

3.6 Attachment Filter Tool

Prevent uploading of attachments which have disallowed file types. 

3.7 Redirection Addon for Confluence

Redirection Plugin macros and their usage (12/15/2021)

• alias (141)
• redirect (16)

3.8 ServiceRocket Composition Plugin

Composition macros and their usage (12/15/2021)

• float (24)
• composition-setup (8)
• deck (6)
• card (6)
• show-card (4)
• cloak (2)
• toggle-cloak (2)

Documentation: https://docs.servicerocket.com/composition/macro-reference

3.9 Visibility for Confluence

Visibility for Confluence macros and their usage (12/15/2021)

• show-if (1495)
• hide-if (9)

3.10 Linking for Confluence

Linking for Confluence macros and their usage (12/15/2021)

• link-to (3)

3.11 Advanced Tables for Confluence (Bob Swift)

Advanced tables allows for tables in a page to be sorted by clicking on one of the column headings. 

Bob Swift Atlassian Apps - Advanced Tables macros and their usage (12/15/2021)

• table-plus (31)

3.12 Refined Theme 

Theme used for SWEHB look and Feel. Custom headers and Footers. 

3.13 Confluence Advanced Macros 

Used extensively: 

confluence-advanced-macros macros and their usage (12/15/2021)

• include (1198)
• excerpt (843)
• excerpt-include (366)
• children (69)
• gallery (6)
• recently-updated (2)
• popular-labels (2)
• search (1)

3.14 Content Formatting

Content Formatting for Confluence macros and their usage (12/15/2021)

• div (1413)
• table (43)
• td (43)
• tr (43)
• span (23)
• th (15)
• tbody (12)
• style (8)
• auitabspage (2)
• thead (2)
• auitabs (2)

3.15 Layout Macros

Layout Macros macros and their usage (12/15/2021)

• section (414)
• column (404)

3.16 Information Plugin

confluence-information-plugin macros and their usage (12/15/2021)

• note (480)
• info (156)
• tip (9)
• warning (4)

3.17 Expand Macro

Confluence Expand Macro macros and their usage (12/15/2021)

• expand (206)

3.18 Wiki Markup Plugin

Wiki Markup Plugin macros and their usage (12/15/2021)

• unmigrated-wiki-markup (126)
• unmigrated-inline-wiki-markup (3)

3.19 Confluence View File Macro

Confluence View File Macro macros and their usage (12/15/2021)

• view-file (17)

3.20 Code Macro Plugin

Code Macro Plugin macros and their usage (12/15/2021)

• code (13)

3.21 Table of Contents Plugin

Table of Contents Plugin macros and their usage (12/15/2021)

• toc (10)

3.22 Confluence HTML Macros

Confluence HTML Macros macros and their usage (12/15/2021)

• html (7)

3.23 Page Tree Plugin

Page Tree Plugin macros and their usage (12/15/2021)

• pagetree (2)
• pagetreesearch (2)

3.24 Bob Swift Addons - Cache

Bob Swift Atlassian Add-ons - Cache macros and their usage (12/15/2021)

• cache (3)

3.25 Dashboard Macros

Dashboard Macros macros and their usage (12/15/2021)

• recently-updated-dashboard (1)

3.26 Basic Macros

Basic Macros macros and their usage (12/15/2021)

• panel (1759)
• anchor (148)
• noformat (2)
• loremipsum (1)

3.27 Dashboard Macros

Dashboard Macros macros and their usage (12/15/2021)

• recently-updated-dashboard (1)

 4. User Macros

4.1 User Macros

User macros are custom developed by the SWEHB maintenance staff. 

4.2 Macro Packages

Macro packages are used to add capabilities beyond the native capabilities of Confluence. In SWEHB, these macro packages include: 

Macro usage

Unused macros

The following macros are provided by user-installed apps and are not used on any pages (not including pages in archive spaces). This information is helpful if you're about to disable or remove an app and want to make sure its not used on any pages.

All macros

This list shows how often each macro is used in your site. We've organised the list by the app that provides the macro, and included both user-installed apps and apps bundled with Confluence.

 5. Content

The content of the SWEHB is contained in the various spaces that have been created over time. Each version of NPR7150.2 has a unique space for it's content. 

5.1 Spaces

The original SWEHB was implemented in space 7150.  Over time, spaces were added to accommodate more versions of NPR7150.2. At present, 4 versions of the SWEHB are in use: 

Some associated functionality is located in the SITE space. https://swehb-pri.msfc.nasa.gov/pages/reorderpages.action?key=SITE 

This space contains: 

• SWE History Summary  - and history pages for all SWEs
• Terms - old database of terms. was used with the "TERM" macro. The macro no longer works so the database has been reduced to a glossary page of terms
• Archived References - Retired references with a PDF copy of the old document attached to the SWEREF page. 
• Process Asset Templates - Content from the SWEHB that have been turned into downloadable templates for projects to use or adapt to their project. 
• Change History for all SWEHB versions
• Development Area and Tools - for experimenting with new ideas
• Documentation of SWEHB Architecture and Style Guides - This content
• Power Tools for SWEHB - helpful code samples
• Term Tools - old Tools Table and associated Tools Pages 

5.2 Content pages

There are several types of pages used in the SWEHB. 

• Book A. Introduction - Top level landing page for SWEHB.NASA.GOV
• B. Institutional Requirements - List of SWE page links for chapter 2 of NPR 7150.2
• C. Project Software Requirements - List of SWE page links for chapters 3, 4, and 5 of NPR 7150.2
• D. Topics - List of topic groupings and links to the pages
• E. Tools, References and Tools - Links to a small number of special pages 
• F. SPAN - instructions on accessing SPAN in NEN
• FAQ - Frequently asked Questions for various groups of users
• SWE pages - Requirements and associated guidance based on NPR 7150.2 - 
  • These pages are documented in detail in the SWE Style Guide and Template.
  • Detailed instructions on maintenance of these pages is in SWE Maintenance Guide. 
• Topic pages - Special topics and associated guidance based on NPR 7150.2 - See Topic Style Guide and Topic Maintenance Guide for additional details. 

 6. Maintenance

Production and Staging Sites

The copy of the SWEHB on the Production server is where all content maintenance is performed. When testing of Confluence and platform level software releases need to be performed, a copy of the production content is put onto the Staging server. Testing of the platform software changes is then done to make sure there are no regression issues between the software running on Production and Staging. If there are no issues, Production software may be updated. 

Macro Changes

Any changes to User Macros are made first on the Staging server. Once the changes are tested and proven, the macro code is manually copied to the Production server. Backup of macro code is the responsibility of SWEHB maintainers and MSFC IT so that a trustworthy method of reverting to Known Working Code is maintained. 

Reviews on References

All references are updated as changes are brought to the attention of the SWEHB Maintainer. An annual review of all references is made to ensure that the appropriate version of each reference is available through a live (not redirected) link. As a part of this review, a change history on the reference is maintained. 

See References in SWEHB for details on how references are handled and maintained. 

New Versions of the SWEHB and NPR7150.2

 As each new version of the NPR are released, new SWEHB versions are built and released. Each new release of the SWEHB is contained in its own space on the Confluence Server. At a high level, as each SWEHB version is built the following maintenance is performed on the new space: 

1. A new space is created on the server along with a new theme (header and footer materials). 
2. A full copy of the prior version of the SWEHB is copied into the new space. 
3. All internal links on all pages are reviewed for referential integrity (point to appropriate pages in the space). 
4. All changes from the NPR are reviewed and made on the appropriate pages.
   1. SWEs are added as necessary,
   2. Deleted SWEs are moved to the Retired SWE portion of the Protected Area. 
   3. Changes to SWEs are made as appropriate. 
   4. Applicability Matrix information is updated.
5. All pages are flagged for Content Review by a SME. Changes are made and reviewed as necessary. 
6. All quotations are flagged and checked to see that the current source document actually contains the quotation. For quotations that have changed in the source document, the SME for the SWE or Topic is notified to update or remove the quote. 
7. All diagrams and external materials are reviewed for applicability. Old materials are removed. New or changes to existing materials are made. 
8. Updates to all SWEs in the SWE History area are performed. 
9. Topics are reviewed and flagged for updating by the appropriate SME. Changes are made as necessary. 
10. All references are reviewed and updated as necessary. 
11. Updates to other pages are made as necessary including
    1. Tools Table
    2. Acronyms
    3. Terms
    4. PATs

A final review of content is performed before the new SWEHB is released. Releasing consists of IT making the new SWEHB the Home page for Confluence. In that way, the URL "SWEHB.NASA.GOV" will take users to the new Home page. Anonymous users are given only View permission to the new space. 

Large Scale Updates and Changes

While minor changes can be made directly in a page, large scale changes that take many days to implement, need a different approach. The full details of the process for making changes is described in the attached PowerPoint presentation SWEHB Branching and Merging.pptx. A brief overview is included below. 

SWEHB Branching and Merging 

• Branch: The page to be changed has a child page added to it where changes will be made and tested. 
• A full copy of the parent page is made in the child page. The child page is only available to reviewers who have a URL to it. 
• All changes are made in the tabsetup macro of the child.
• Changes may be reviewed by any number of reviewers who have been given the URL to it.
• Merge: When changes are deemed acceptable, the entire contents of the tabsetup macro are copied to the parent page. This puts the changes into production and makes them available to everyone.