1. Introduction
The content of the SWEHB Style Guide is divided into the following main areas, 1.1 Overall Look and FeelThe Look and Feel of the SWEHB is the main focus of this page. It covers:
1.2 Features and ToolsThe SWEHBDOC Features And Tools page contains details on:
1.3 Maintenance Of SWEHBThe SWEHBDOC Maintenance page contains details on:
|
2. Look And Feel Of SWEHBThe Look and Feel of the SWEHB is implemented in two ways. The page Header / Footer, and the page layout implemented with the tab structure. See SWEHBDOC Refined Themes for details on how the header and footer are administered using the Refined Theme Plugin. As you read the sections below, also look at the page Header and Footer areas on this page. 2.1.1 HeaderAt the top of each page is the Header. This area contains several elements that help the SWEHB user to navigate through the handbook. Follow along on this page to see the elements discussed below:
2.1.2 FooterAt the bottom of each page is a set of links to the NASA Privacy Statement and email links to the Curator of the SWEHB. 2.1.3 Page LayoutEach page that users see is structured in a tabular format. The tabs are built using the "tabsetup" User Macro. See SWEHBDOC Tabs In SWEHB Pages for details. All SWE pages are constructed with the same set of tabs. Topic pages may have a different tab structure but will always have a "Resources" tab. |
3. Top Level Pages3.1 High Level StructureThe structure discussed here is the logical structure. The logical structure is mimicked by the pagetree which has a few obvious differences to facilitate maintenance of a version. The structure of the SWEHB (links are to pages in SWEHBVD for reference) is:
3.2 Page Top MessagesTo facilitate getting important messages out to users quickly, a system of "Page Top Messages" has been created. The Page Top Messages page is under Page Sections in the SWEHBVD pagetree. It fully explains the details you will need to use these messages. For example, If you want to put a message at the top of all SWE pages, You would go to the 2D-SWE Page Message page and follow the directions in that page. You would come up with a message, put it into the designated place in the 2D-SWE Page Message page and save it. Then you would see your message on the 2D-SWE Page Message page as well as any SWE page you go to. It will appear on the SWE page because of an Excerpt-Include macro which is at the top of every SWE page. Each of the four page top message pages has a similar layout. You can tailor what you want to say in each of the four types of pages. When building new pages it is necessary to put an Excerpt-Include macro at the very top if the page should participate in this feature. 3.3 Top Level PagesTop Level Pages are used as navigation aids for users to find types of content in the SWEHB. They are all unique in their design and are discussed below. To follow the descriptions, you can open each in a new window as you go along. 3.3.1 Book A. IntroductionThis is the home page for the version of the SWEHB that corresponds to a version of NPR 7150.2. Book A. Introduction.
3.3.2 - RequirementsThere are two requirements pages in the current version of the Handbook: The layout of these pages is similar and explained below:
The balance of the pages are devoted to groups of requirements.
3.3.3 D. TopicsThere is one D. Topics page. It has:
3.5 E. Tools, Refs, TermsThe E. Tools, References, and Terms contains:
Each link goes to a specific page. Each page contains details on where the page comes from or is built from.
3.6 Other Pages3.6.1 - FAQThe FAQ - Engineering, Assurance, and Safety page is a compilation of Frequently Asked Questions about the SWEHB. It is maintained by the Page Editor and is organized in the following tabs:
Each question and answer may have links to supporting SWEHB pages. 3.6.2 - BlogBlog 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. |
4. SWE - Requirement Page Style4.1 Page TitleThe title of the SWE has two parts. For Example: "SWE-987 This Is the Title"
The 7 character prefix is used by the References macros. When the HR requirements were added the numbering was managed to always ensure a 7 character prefix in SWEREFs and elsewhere.
4.1.1 Creating a new SWE PageIn the directory tree for a SWEHB version space there is a page for "SWE Pages". This is the container for all active SWEs in the version. In the Protected Area, there is another container for "Retired SWEs". All possible SWEs, used or reserved so far, are found in one of these containers. If you are creating a new SWE page, start by opening, in a new tab, a page from the SWE Pages container.
4.2 Tabbed Presentation Of ContentThe content of most pages in SWEHB uses the TABSETUP User Macro. This macro serves as a container and organizer of content in a tabbed format. You can use any existing SWE as a model for following along with the descriptions below. For details on "tabsetup" see 4.2.1 Configuring TABSETUPAfter inserting the TABSETUP macro, edit the macro and enter the titles for each of the tabs. In SWEHB, tabs are numbered. It is best to keep the tab title short to reduce overflow across the page. See SWEHBDOC Tabs In SWEHB Pages for additional details. 4.2.2 Configuring a DIVEach tab is implemented using a DIV macro. Each DIV is edited and contains only an ID parameter. The format of the ID parameter is "tabs-1", "tabs-2", etc. The first line in the body of a DIV should be the numbered the same as the tab title. The text style should be "Heading 1". Subsequent subdivisions in the DIV may use styles like "Heading 2", "Heading 3", etc. to organize content. Further detail in using all macros is included in the various maintenance guides. 4.2.3 Tips on tabsetup and DIVs
4.3 Organization of a SWE or HR pageEach requirement is organized the same way. Project Software Requirements have an extra tab (tab 7) for Software Assurance. If you are building a new page, the simplest thing to do is
4.4 Tabs In A Requirements PageThis describes the structure in a requirements page. Content unique to the requirement is organized the same way for each requirement page to make it easy for the user to find things. 4.4.1 Requirement tab1. Requirement - contains an EXCERPT macro with the text of the requirement in it. This facilitates reusing the text of the requirement in other SWEHB pages (using the EXCERPT INCLUDE macro) 1.1 Notes - contains the text of the "Notes" for the SWE taken directly from the NPR 7150.2. If there is no Notes section, the text "NPR 7150.2, NASA Software Engineering Requirements, does not include any notes for this requirement." 1.2 History - Contains a link to the History page for the SWE. History pages are located in the SITE space. There is a page for each SWE. On each page is a table with the text of each SWE by NPR 7150.2 version SWE. Between each version of the SWE text is a row describing the differences between the SWEs. 1.3 Applicability Across Classes - contains a table displaying the content of the applicability of the SWE for each of the software classes. It is either Applicable or Not Applicable. Applicability is assigned in an appendix in the NPR 7150.2. Applicability is only included for SWEs that appear in the matrix in the appendix of the NPR 7150.2. See SWEHBDOC - User Macros in SWEHB for details on using the Applicability macro. 1.4 Related Activities - contains a list of the Activities that the requirement belongs to. These links are stored in the "Related Activities" page for the Requirement. This will need to be created under a new requirement. 4.2.2 Rationale tab2. Rationale - short statement explaining why the SWE is a requirement. This expands on the requirement and notes from the prior tab. 4.2.3 Guidance Tab3. Guidance - explains how the requirement can be implemented. It may include:
4.2.4 Small Projects4. Small Projects - Guidance on how the requirement can be satisfied by small projects. In some cases, small projects may get a waiver for the requirement. 4.2.5 Resources5. Resources 5.1 References - contains a macro / report of SWEREFS that are called out in the page. See SWEHBDOC References in SWEHB.
5.2 Tools - an include page describing the tools library. Other sections as necessary to list other resources such as PATs, etc. 4.2.6 Lessons Learned6. Lessons Learned 6.1 NASA Lessons Learned - bulleted list of items from the NASA Lessons Learned Database.
6.2 Other Lessons Learned (add this category only if appropriate)
4.2.7 Software Assurance7. Software Assurance - includes am "excerpt-include" macro pointing to the requirement excerpt in tab 1. The requirement is repeated here to reinforce what SA is responsible for. 7.1 Tasking for Software Assurance - includes tasking taken from the NASA-STD-8739.8B that is relevant to the requirement. 7.2 Software Assurance Products - a list of the SA products that are expected to be created or updated as part of the requirement. Objective Evidence list of evidence items to be created or updated. 7.3 Metrics - a list of metrics to be collected in the performance of the requirement. 7.4 Guidance - Additional guidance, beyond that in tab 3, and focused specifically on what SA is responsible for. 7.5 Additional Guidance - Lists of links from "Related SWEs" and "Related SM" pages. 4.2.8 Objective Evidence8. Objective Evidence - This came from the tab 7 content and has been made into its own tab. |
5. Topic Page StyleTopics have been included in SWEHB since the first version in 2011. They have been modified over the years to include:
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. 5.1 Page TitleThe title of a Topic has two parts. For Example: "7.10 This Is the Title"
The 4 character prefix is used by the References macros. 5.1.1 Topic NumbersThere are several numbering groups currently in use. If the new topic fits in one of these groups, you may assign the next number in the sequence to the topic. If you need to start a new group, there will be some additional steps below to accommodate this.
5.1.1 Creating a new Topic PageIn the directory tree for a SWEHB version space there is a page for "Topics Pages". This is the container for all active Topics in the version. In the Protected Area, there is another container for "Retired Topics". All possible Topics, used or reserved so far, are found in one of these containers. If you are creating a new Topic page, start by opening, in a new tab, a page from the Topics Pages container. This will ensure that the new page is properly located in the pagetree.
5.2 Tabbed Presentation Of ContentThe content of most pages in SWEHB uses the TABSETUP User Macro. This macro serves as a container and organizer of content in a tabbed format. You can use any existing Topic as a model for following along with the descriptions below. 5.2.1 Configuring TABSETUPEdit the "tabsetup" macro and enter the titles for each of the tabs. In SWEHB, tabs are numbered. It is best to keep the tab title short to reduce overflow across the page. See SWEHBDOC Tabs In SWEHB Pages for additional details. 5.2.2 Configuring a DIVEach tab is implemented using a DIV macro. Each DIV is edited and contains only an ID parameter. The format of the ID parameter is "tabs-1", "tabs-2", etc. These numbers correspond to the tab numbers. The first line in the body of a DIV should be the numbered the same as the tab title. The text style should be "Heading 1". Subsequent subdivisions in the DIV may use styles like "Heading 2", "Heading 3", etc. to organize content. Further detail in using all macros is included in the various maintenance guides. 5.2.3 Tips on tabsetup and DIVs
5.3 Organization of a Topic PageEach topic is organized in a similar way. For a new topic you will need to buildout the tabs and DIVs for the content.
5.4 Tabs In A Topic PageThis describes the structure in a requirements page. Content unique to the requirement is organized the same way for each requirement page to make it easy for the user to find things. See SWEHBDOC Tabs In SWEHB Pages for additional details. 5.4.1 Introduction of Purpose TabThis is the first tab in a topic. It contains an overview of the subject matter in the topic. It gives the reader a high level view of what is contained in the other tabs. 5.4.2 Content TabsThere can be as many content tabs as you need to present the material in the topic. Use them to organize the material in a logical fashion. 4.2.3 Guidance Tab 3. Guidance - explains how the requirement can be implemented. It may include:
5.4.3 Resources TabThe resources tab is where the references are listed and other supporting materials are organized. The typical headers are: 5. Resources 5.1 References - contains a macro / report of SWEREFS that are called out in the page. See SWEHBDOC References in SWEHB.
5.2 Tools - an include page describing the tools library. 5.3 Additional Guidance - contains a table of the contents of the "Related SWEs" and "Related SM" pages. 5.4 Center Process Asset Libraries - contains a list of SPAN pages related to the subject of the topic. 5.5 Related Activities - contains a list of Activities in the Activities View that pertain to the topic. 5.4.4 Lessons LearnedThis is a n optional tab that should be added only if there are applicable Lessons Learned from either NASA, a Center, or another source, for the topic. 6. Lessons Learned 6.1 NASA Lessons Learned - bulleted list of items from the NASA Lessons Learned Database.
6.2 Other Lessons Learned (add this category only if appropriate)
|
6. PAT Page StyleProcess Asset Templates are a natural evolution of guidance in SWEs and Topics. They typically start out as checklists, process step lists, document content structures, or other content and evolve into templates that can be used in project activities or as prototypes to be modified, tailored, and improved before being used in a project. Process Asset Templates is a general category of pages. These pages include:
A PAT is numbered so that existing code in templates and macros for references and tools can be reused. The PAT number series will be included in the first 7 characters of the page title. This code is used in PAT reports, and the PAT Database. For full details on PATs see SWEHBDOC PAT - Process Asset Templates In SWEHB. |
7. Activity Page Style
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:
7.1 Activity Page OrganizationLarge Activities, like Software Life Cycle Planning, have multiple tabs. Smaller activities fewer tabs. Each activity is divided into two sections:
7.2 Maintaining Activity PagesThe pages are designed to be simple to maintain. They are just bulleted links to pages with excerpts from those pages displayed. The real work in maintaining the activities comes when changes are made to SWEs, Topics, PAT pages. Frequently a change in a page triggers a change in other pages.
This builds a multidirectional cross-referencing among pages. In the activity View there is a list of detail pages which can be used to help maintain the Activity Pages. These have much more detail collected from the "Related" pages attached to each SWE and Topic page in the Handbook. The pages with two levels of numbering (such as "A.01.01 Planning the Work") include:
|
8. Frequently Asked Questions - FAQThe FAQ pages are a collection of Frequently Asked Questions that apply to:
Questions are listed on the appropriate tab with the Answer immediately below. References that are provided point to the Resources tab and a References List like any SWE of Topic page. The page is organized into tabs and the General Questions are included at the bottom of all tabs (using an Include Page macro). See FAQ - Common Frequently Asked Questions for Engr, SA, Safety. The link to the FAQ Page appears in the page top information on the D. Topics page. |