Maintenance Guide for Topic pages.
See edit history of this section
Post feedback on this section
- 1. Introduction
- 2. Engineering Topics
- 3. Assurance and Safety Topics
- 4. Software Design Principles
- 5. Programming Checklists
- 6. FAQ
- Numbering Categories
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 Type | Topic Series | Component Description |
---|---|---|
Process | 1.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:
|
Cybersecurity Topics | 2.xx | In depth guidance on Software Cybersecurity topics. |
Software Safety Topics | 3.xx | In depth guidance on Software Safety topics. |
Review | 4.xx | List of things to do or consider when performing a development or assurance task in a project. Usually includes Items for:
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 Content | 5.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. |
Checklist | 6.xx | List 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 Topics | 7.xx | In depth guidance on Software Engineering topics. |
Software Assurance Topics | 8.xx | In depth guidance on Software Assurance topics. |
Software Design Principles | 9.xx | Software 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. |
Activities | A.xx | SWEHB 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.
- Select the group of items to be numbered. For example, Software Design Principles.
- Select the numbering series. For example, 9.xx
- For each page, do the following changes:
- Open "Page Information" for the page being edited
- Edit the page and change the title by adding the number. For example, "9.01 Software Design Principles"
- Check each of the "incoming pages" to verify the change of the page title
- updated any pages where the title did not update.
- 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.
- 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.
- 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:
- Page Number to be added to title
- Incoming / Fixed - from Page Info cleanup
- Refstable topic added - macro added to resources
- # Refs / fixed - references fixed by adding number
- Del InclPage for coded refs - once new and old lists match, delete list based on added code
- # SWE links in page - how many SWE links to SWEHHBVD are in page - for moving principles into SITE - need to rmv links.