bannerd

A. Introduction

B. Institutional Requirements

C. Project Software Requirements

D. Topics

E. Tools, References, and Terms

F. SPAN
(NASA Only)

Maintenance Guide for Topic pages. 

Topic Maintenance Guide

1. Introduction

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

  • Engineering Topics
  • Assurance and Safety Topics
  • Software Design Principles
  • Programming Checklists
  • FAQ - Engineering, Assurance, and Safety

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

1.1 Page Structure

Refer to the D. Software Topics page for the source code for the page. It is constructed using a series of HTML Table, Table Row, Table Cell commands in Confluence. There is a CSS Style sheet section, a TABSETUP section (for the tabs), and additional HTML Table, Table Row, Table Cell commands to force the structure of the page within the tabs. 

Generally, the tabs are two columns of links to topic pages along with an excerpt from the topic page explaining what the topic is about. 

Each cell contains a link to the topic page, followed by an "Excerpt Include" macro to pull the excerpt from the topic page. 

1.2 Numbering of New Topic Categories - 2023

Numbering of some existing and new categories is summarized in the table below. Procedures will be developed in Numbering Procedures of this page. 

Component TypeTopic SeriesComponent Description
Process1.xx

Regularly performed set of actions with an expected set of outcomes. An example might be a generic Peer Review Process. A process usually contains: 

  1. Triggers that cause the process to be initiated
  2. Inputs
  3. Process Steps which may be performed in a sequence or simultaneously
  4. Outputs
  5. Follow up actions, e.g. defects that need to be fixed
Cybersecurity Topics2.xxIn depth guidance on Software Cybersecurity topics. 
Software Safety Topics3.xxIn depth guidance on Software Safety topics.
Review4.xx

List of things to do or consider when performing a development or assurance task in a project. Usually includes Items for:

  • Preparing for the review
  • Actions taken during the review
  • Actions taken after the review

This would initially be populated by taking apart topic 7.09 - Entrance and Exit Criteria with each tab (review) becoming a numbered page. This would allow individual pages to be included in a SWEHB Activity without pulling in the whole of 7.9. We could keep 7.9 and pull in all of the new pages if needed to keep topic 7.9 in its place. 

This would allow for the documenting other types of Reviews beyond just those in 7.9. 

Document Content5.xx

Describes the minimum content expected in a particular document.

This would get us back to the concept of "minimum content of a document" like in the original SWEHB version (space 7150). Each document would be represented by an individually number page in this series. Individual pages could be also be included in other topics as necessary.

This is a numbering sequence that needs to be implemented so that hardcoding of references tables can be eliminated. 

Checklist6.xxList of things to consider when performing some development or assurance task in a project. Checklists are frequently also built into a Process Asset Template (PAT). The PAT is included in the Checklist page so there is only one place to update the Checklist. 
Software Engineering Topics7.xxIn depth guidance on Software Engineering topics. 
Software Assurance Topics8.xxIn depth guidance on Software Assurance topics.
Software Design Principles9.xxSoftware Design Principles. This is a numbering sequence that needs to be implemented so that hardcoding of references tables can be eliminated. 
PAT (Process Asset Template)PAT-xxx

List of things to do or consider when performing a development or assurance task in a project. PATs are formatted into documents that can be downloaded by projects and used or tailored for use in a project.

These may be used and included in any of the other Topic series. This series number format will allow using the "refstable" macro to select references if we allow references to be assigned to a PAT. 

ActivitiesA.xxSWEHB Activity View series. This series number format will allow using the "refstable-topic" macro to select references if we allow references to be assigned to an Activity.
Other Series
The use of a 4 character key for pages is what would allow for building unique search keys for finding references and building the reference list for pages. once we run out of numbers for the first character, we can move on to alpha characters. Using A for Activities is the first use of this technique. For more series, we could move on to "B.xx", "C.xx", ..., "Z.xx". 

2. Engineering Topics

Engineering topics are all found in under the Topics Pages in the page tree for the SWEHB version. Some older SWEHB versions have a slightly different mechanism for organizing the topics. 

All topics start with a four character number formatted "9.99". This allows the referencing macros to work properly. See References in SWEHB. Engineering topics are in the 7 series, like "7.99". 

Retired topics are removed from the SWEHB version and a false link is entered in the topics table as a place holder. The false link says "Topic Retired" in blue text. 

3. Assurance and Safety Topics

Assurance and Safety topics are new in SWEHBVC. They are all found in under the Topics Pages in the page tree for the SWEHB version. Some older SWEHB versions have a slightly different mechanism for organizing the topics. 

All topics start with a four character number formatted "9.99". This allows the referencing macros to work properly. See References in SWEHB. Assurance and Safety topics are in the 8 series, like "8.99". 

Retired topics are removed from the SWEHB version and a false link is entered in the topics table as a place holder. The false link says "Topic Retired" in blue text. 

4. Software Design Principles

Software Design Principles are new in SWEHBVC. They are all found in under the Topics Pages in the page tree for the SWEHB version. Some older SWEHB versions have a slightly different mechanism for organizing the topics. 

All Principles do not have a special numbering in the title. This requires a different numbering scheme to use the referencing reporting to work properly. See References in SWEHB. 

Retired topics are removed from the SWEHB version and a false link is entered in the topics table as a place holder. The false link says "Principle Retired" in blue text. 

4.1 Numbering of Principles

RENUMBER IN SWEHBVD AND INCLUDE TEH RATIONAL HERE

5. Programming Checklists

Engineering topics are all found in under the Topics Pages in the page tree for the SWEHB version. Some older SWEHB versions have a slightly different mechanism for organizing the topics. 

All topics start with a four character number formatted "9.99". This allows the referencing macros to work properly. See References in SWEHB. Programming Checklists are in the 6 series, like "6.99". 

Retired topics are removed from the SWEHB version and a false link is entered in the topics table as a place holder. The false link says "Checklist Retired" in blue text. 

6. FAQ - Frequently Asked Questions

Additional .

7. Numbering Categories

Numbering uses the following process. 

  1. Select the group of items to be numbered. For example, Software Design Principles.
  2. Select the numbering series. For example, 9.xx
  3. For each page, do the following changes: 
    1. Open "Page Information" for the page being edited
    2. Edit the page and change the title by adding the number. For example, "9.01 Software Design Principles"
    3. Check each of the "incoming pages" to verify the change of the page title 
      1. updated any pages where the title did not update. 
    4. In the resources tab of the changed page, add the macro "refstable-topic" into 5.1.  Verify that it works and displays "No references ..." initially. 
      1. For each reference in the refs table (using the Include Page), add the new series title number in the Associated SWEs field. (be sure to put "Topic " in front of each topic entry.) Verify that the reference is pulled into the "refstable-topic" macro. 
    5. Once all references are appropriately listed by the new numbering, delete the "Include-Page" for the old code for references. 

Process created in Main spreadsheet with headings: 

  1. Page Number to be added to title
  2. Incoming / Fixed - from Page Info cleanup
  3. Refstable topic added - macro added to resources
  4. # Refs / fixed - references fixed by adding number
  5. Del InclPage for coded refs - once new and old lists match, delete list based on added code
  6. # SWE links in page - how many SWE links to SWEHHBVD are in page - for moving principles into SITE - need to rmv links. 
  • No labels

0 Comments

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
______________________________________________________________________________