Notes on needed updates

Content updates needed on this page:

Full cleanup in 2 - 5

SWEHBDOC - Documentation of SWEHB

Web Resources

View this section on the website

See edit history of this section

Post feedback on this section

Section Labels:

Unknown macro: {page-info}

1. Introduction
2. Architecture
3. SWEHB Style Guide
4. Editor Tips and Tools
5. SWEHB Maintenance
6. How Do I ...

1. Introduction

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

The design accounted for only one version, the most current at the time, would be published in space “7150”. Fundamental design changes were necessary to accommodate multiple versions of the Handbook in the SWEHB site.

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 next version will be based on NPR 7150.2E and be included in space “SWEHBVE”.

1.1 Additional documentation

The documentation includes details about how the SWEHB is built and maintained. Style Guides for certain types of pages are included as pages under this page.

SWEHBDOC Architecture — The Architecture of the SWEHB spaces is discussed in this page. It includes the basic Confluence Platform, add-on software like plugins and macro bundles, themes, and a small amount of user (NASA) written macros that give the SWEHB its look and feel.
SWEHBDOC Basic Style Guide — 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.
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.
- SWEHBDOC References in SWEHB — Explains how references are used and maintained in SWEHB.
  - SWEHBDOC Add A Reference To A Page
- SWEHBDOC 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.
- SWEHBDOC Sticky Headers — Sticky Headers is a feature of HTML. When a header row is made "sticky" it will remain visible when the user scrolls down on the page. It is particularly helpful when there are a large number of columns and the user needs to see the column heading when they are down deep in the table.
  - 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.
- SWEHBDOC Editor Tools and Tips — This page contains Editors Tools and Tips. These documentation pages describe how to use some of the features of Confluence along with other tools and tips that are used in maintaining SWEHB.
  - SWEHBDOC Branch and Merge Process — The Branch and Merge Process is used for Large scale changes to pages in SWEHB.
    - SWE-876 - Programming Code
  - SWEHBDOC Keyboard Shortcuts — This table includes Keyboard Shortcuts for various editors and browsers including Chrome, Word and Confluence.
  - SWEHBDOC Redirect Tools — This page is a collection of tools that are helpful in troubleshooting redirection in SWEHB pages in all versions.
  - SWEHBDOC Managing Hyperlinks — This page describes the use of Relative Links and Absolute Links in Confluence.
  - SWEHBDOC Table Cell Color Palette — Colors used in Confluence Tables for backgrounds.
  - SWEHBDOC Power Tools for SWEHB — This page is a collection of tools that are helpful in troubleshooting SWEHB pages in all versions. Included are "Opening a Page in Edit Mode", "Finding Macros in Pages".
  - SWEHBDOC - Templates used in SWEHB — Source code for templates is documented in PATs and References:
    - 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
  - SWEHBDOC Tabs In SWEHB Pages — This covers the "tabsetup" macro and how to use it.
- SWEHBDOC Include Macro Usage in SWEHB — Explains how the two types of "Include" macros are used n SWEHB.
- SWEHBDOC - Eliminating the tabsetup Macro — If tabsetup is not available, how can we emulate the page layout to simulate the tab method of displaying content.
  - SWE-961 Coding Standards — 4.4.3 The project manager shall select, define, and adhere to software coding methods, standards, and criteria.
  - SWE-961 Coding Standards - Requirements — 4.4.3 The project manager shall select, define, and adhere to software coding methods, standards, and criteria.
  - SWE-961 Coding Standards - child pages
- SWEHBDOC - Replacing Refstable Macros — By using the Excerpt method of managing SWEREF data, the display macros are no longer necessary and the Confluence template can be retired as well.
- SWEHBDOC - User Macros in SWEHB — Macros used in SWEHB spaces
  - Macros not used — This page contains User Macros that are not used in any space.
  - 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.
- SWEHBDOC PAT - Process Asset Templates In SWEHB — PATs in SWEHB were added in 2023. They are templates, mostly of checklists, that projects may use and adapt as necessary.
SWEHBDOC Maintenance — The maintenance of SWEHB includes daily Health Checks as well as larger additions of features and functionality. Some of these new features must be developed, tested and incorporated into the overall SWEHB. This section covers all of the known forms of maintenance currently used in maintaining SWEHB.
- SWEHBDOC Daily Healthcheck
- SWEHBDOC Document Archive
- SWEHBDOC Quotes in SWEHB — Explains how quotes are used and maintained in SWEHB.
- SWEHBDOC Version Space
- SWEHBDOC Refined Themes
- SWEHBDOC Content Style and Consistency — Content writing style and consistency notes.
  - SWEHBDOC Consistency of Language
- SWEHBDOC Quotations in SWEHB — Quotations structure and maintenance are described here.
- SWEHBDOC - New Page or Updated Page
  - Checklist for New SWEHB Page — This checklist is for the new SWEHB page:
  - Checklist for Updated SWEHB Page
- SWEHBDOC - New Version of SWEHB — As new versions 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:
  - Dev Area For New Version Of SWEHB - SWEHBVE — A Development page for the new version is being created in parallel with this new version. The development page is . It will be referenced in the checklist as necessary.

1.2 User Access

Access to the SWEHB is granted to anyone who can get to it through 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. Architecture

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

The architecture of the SWEHB system has been derived over the period of 2010 to today. It was originally built on a server at GSFC and later migrated to MSFC. The servers and network access are the responsibility of an organization under MSFC known as MSFC-IS61 - NCAPS (NASA Consolidated Applications and Platform Services).

For details, see SWEHBDOC Architecture.

3. SWEHB Style Guide

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.

For details see SWEHBDOC Basic Style Guide.

4. Features and Editor Tools and Tips

For details see:

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.

SWEHBDOC Editor Tools and Tips - This page contains Editors Tools and Tips. These documentation pages describe how to use some of the features of Confluence along with other tools and tips that are used in maintaining SWEHB.

5. SWEHB Maintenance

For details on regular maintenance activities see SWEHBDOC Maintenance.

5.1 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. More details on these spaces is available in the SWEHBDOC Architecture page.

5.2 Backup and Restore Of Spaces

IT is responsible for all backups and restoring of spaces.

6. How Do I ...

This section covers some typical scenarios in SWEHB maintenance. Each describes the problem and provides links to SWEHBDOC pages where help can be found.

6.1 Make Content Corrections In A Page?

Simple content corrections on a page may be done using the editor.

When you are viewing the page, click on the Edit command in the bar just above the page Title. This will open the page in the WYSIWYG editor.
You will see "frames" representing macros in the page. In the "tabsetup" frame you will see additional "Div" frames. These contain the content organized in a fashion very similar to a MS Word document with subheadings. Scroll down to the text you want to change and make the edits, adds, deletes, changes.
Use the styles in the editor menu bar (dropdown menu starts with "Paragraph") if you want to convert a line to a header style.
If you want to leave a note in the Page History Comments regarding what changes you made, put a short description in the "What did you change?" box at the bottom of the editor.
If you want to Preview the page in the editor, be aware that it will not be displayed in a tabbed format.
Be sure to Save your changes.
View your changes to be sure that everything looks correct.

Things to be aware of

All of the content in a page is contained in "Div" macros. These correspond to the tabs on the page.
To quickly find the text you want to change, use the find command in the editor. Ctrl-F opens a Find area at the top of the editor. put in part of the text you want to find and hit Enter or Next to get to each occurrence on the page.

6.2 Reorganize Content In A Page?

Larger edits require a little more planning. You can copy and paste in the editor just like you do in MS Word. The same keyboard shortcuts work (see SWEHBDOC Keyboard Shortcuts).

You can move content between tabs easily. Just be sure that you are taking these actions within the correct DIVs. You cannot make a selection for a copy across Div boundaries - you will end up selecting the whole DIV.

Be sure to Save your changes and view your changes to be sure that everything looks correct.

Things to be aware of

After moving or changing content, be sure to cleanup any heading styles and paragraph numbering.

6.3 Add Or Change a Reference In A Page?

For full details on References, see the page SWEHBDOC References in SWEHB.

The page SWEHBDOC Add A Reference To A Page provides details for several scenarios regarding references on SWEHB pages.

6.4 Add Or Change Tabs In A Page?

This is covered in detail in the page SWEHBDOC Tabs In SWEHB Pages. The page details adding the macro to a new page as well as adding tabs and moving things around on a page.

6.5 Add Or Change A Blog Post?

Detailed instructions on Blog Posts are in the SWEHBDOC Blogs In SWEHB page. It covers

The history of Blogs in SWEHB,
Creating a Blog Post,
Publishing it to the Intro page (using the "swehb" label),
Viewing the history of all blogs entries.

6.6 Fix A Hopelessly Messed Up Page?

The safety-net for this situation is the Page History. if is in the dropdown menu (the little "..." on the command bar above the page title). When you click on Page History, you will see a history of every saved version of the page since it was created. You may view old pages (open in a different tab), or compare two versions.

If you Restore to an earlier version, you wipe out the versions that followed the restored version. This allows you to get back to a good looking page and them carefully move forward with your changes again.

6.7 Create A New SWE or Topic Page

The instructions for creating each of these page types is in the SWEHBDOC Basic Style Guide.

Tab 4 goes into great detail on creating a requirements page (SWE or HR).
Tab 5 goes into great detail on creating a topic page.

Incorporating it into the appropriate B. Institutional Requirements, C. Project Software Requirements, or D. Topics pages is a matter of looking at where other similar pages are located and inserting it into the proper table.

6.8 Update Descriptions Of A Topics Page in D. Topics

The details of handling Excerpts and the Excerpt-Include are covered in SWEHBDOC Features And Tools in Tab 10 - Excerpt and Include Macros.

There is a detailed example using topic 8.30 from the D. Topics page.

6.9 Hide Pages or Unhide Pages

6.9.1 Hide or Unhide Whole Pages

Hiding and unhiding pages can be done with permissions but that method is not recommended because pages can get lost if an editor goes away or doesn't remember what was done with the page.

The cleanest way to hide a page is to move it (using the pagetree) into the Protected Area. Just create a page in the protected area for your hidden pages and drag / drop the page to be hidden into your hiding place.

It is a very convenient feature of Confluence that hidden pages cannot be viewed or even discovered in a search by a user that doesn't have permission to edit pages.

6.9.2 Hide Parts Of A Page

This is done in almost all pages. You will find a set of macros near the top of a page or in the References section of the Resources tab, that implement the hiding of some content that only editors need to see. Open any SWE or topic page and look for:

Show If macro with a parameter spacePermission = edit
Panel macro with a title "Visible to Editors Only"
Expand macro - this keeps the clutter minimized until the editor wants to expand it and look at the content.

It shows up at the top of the page in a red panel box with the title displayed and a link for "Click here to expand ..."

You can use this technique anywhere in a page where you want to put comments to editors but not want users to see it.

6.10 Check Status Of SWEHB - Daily Health Check

The daily checks I have been running are detailed in SWEHBDOC Maintenance, Tab 2 - Daily Healthcheck.

There is a Healthcheck page in each version of SWEHB. Links to these pages are in the Daily Healthcheck tab. Viewing a Healthcheck page gives you a set of tabs to look at. Each tab exercises a particular macro and you can tell if there is a problem by following the text on the Healthcheck tab.

There is also a section in that tab listing all the pages I check on a daily basis. There is an explanation next to each link describing what I look for on the page.

6.11 Practice Using The Editor

You may practice using the editor and doing most of the things in the documentation by opening pages in the SWEHBVE. The main pages for the SWEHBVE are there. There is also a branch called "Practice Pages" which has copies of several SWEs and Topics that can be used for practicing making changes without hurting anything.

An item in, SWEHBDOC - New Version of SWEHB, in the checklist advises deleting the Practice pages when you are done them so they won't interfere with the copying of SWE Pages and Topics Pages from SWEHBVD to SWEHBVE.

Content

Space Tools