1. Updates to SWEHB Pages

Froom time to time it will be necessary for changes and updates to be made to SWEHB pages. Sometimes these are minor and sporadic, at other times they may be wide ranging and very detailed. All changes will need to be passed through the very small team of SWEHB Editors. These editors will need very specific information from you. 

Some of the information on a SWEHB page is dictated by the formatting and design of the SWEHB. This topic explains what you can expect to change and what components are fixed and controlled by the editors. 

The fixed components are all listed in tab 2. They are form the bones of the page and the data for them comes from documents like NPR 7150.2 and NASA-STD-8739.8. Other components are built from content on the page like references. There is a lot that you can and must provide for the SWEHB page to be helpful to your readers. 

1.1 What Types Of Changes You May Suggest

2. SWEHB Structures

The structures below are divided into SWEs (requirements) and other Supplementary Materials (Topics, Document Structures,  Checklists, Process Asset Templates, etc.) Each page type has a variety of components that you won't be able to change. The components that you will be able to change are clearly listed. They are marked "Author Content"

2.1 SWEs

2.1.1 Tab 1. The Requirement

  • The first item in the tab is the requirement. This is a direct quote from NPR 7150.2. It is put into the SWEHB in a form that allows it to be reused in a number of other places. 
  • 1.1 Notes - This is also a direct quote from NPR 7150.2. It is the Notes section that appears after the requirement statement. If there is no notes in the NPR, then the statement "NPR 7150.2, NASA Software Engineering Requirements, does not include any notes for this requirement" is used as a filler. 
  • 1.2 History - This is a section that contains a link to pages that contain the history of the requirement throughout its history. It is based on versions of the requirement itself. 
  • 1.3 Applicability - This section appears only in Project Software Requirements. It is a graphic representation of the information in the Appendix that contains the Requirements Compliance Matrix for the requirement. 

2.1.2 Tab 2. Rationale

This tab gives a brief explanation of why the requirement is important, and the value it brings to a project. Author Content: You may provide text to describe the value of the requirement in as much detail as necessary. Most rationales are brief since the bulk of the details are covered in the Guidance and other tabs. 

2.1.3 Tab 3. Guidance 

Author Content:  This is where authors have the most input. You may structure your guidance how you see fit. You may: 

  1. Provide as much text as necessary in any type of paragraphs, bulleted lists, numbered lists,
  2. Provide information in tables. (see tab 3 on requirements for tables)
  3. Provide graphic images that you want. (see tab 3 on requirements for images)
  4. Provide callouts to references that are outside of the SWEHB (see tab 3 on requirements for references)
  5. Provide callouts to other SWEs or Supplementary Materials. You may do this by pasting in the full title of the page anywhere you want. Editors will format the title into a link to the page. To make it easy for editors to find these callouts, please underline them. 
  6. Provide text as "Notes" and they will be put into special yellow Notes panels. 

2.1.3.1 Additional Guidance

This is one of those special sections that contains structured material. It is a table of links to other SWEHB pages that have been called out in the Guidance text. Editors will find these callouts and format them appropriately for this section. You can include them in your WOrd Document if you want and then add or remove entries as needed so the editors can find the changes. 

2.1.3.2 Center Process Asset Libraries

This contains structured material. It is a list of SPAN pages that display Center materials for the SWE or Topic. 

2.1.4 Tab 4. Small Projects

Author Content:  This is where authors have input. You may structure your Small Project guidance how you see fit. You may provide text, lists, tables, or other content much like in the Guidance tab. 

2.1.5 Tab 5. Resources

This tab is all structured content. authors provide information that is used here but don't provide direct content for this page: 

  • References Table is built from data supplied from the Guidance tab. The table includes all of the Reference data organized in a bulleted list including the Tltle, URL, Citation and Notes for the Reference. 
  • Tools list - this is static text providing a link to the old Tools list. 
  • Other structures that are built by the editors. 

2.1.6 Tab 6. Lessons Learned

Author Content:  This is where authors have input. You may list Lessons Learned from two sources: the NASA Lessons Learned Database or a Center or other database for Lessons Learned (such as within a referenced document). Provide the content including any quotes from the appropriate database and it will be formatted by the SWEHB editors.  

2.1.7 Tab 7. Software Assurance

This tab contains a mix of Structured items and Author Content items: 

  • The Requirement is re-displayed at the top of the page. 
  • The "Tasking for Software Assurance" is / are quotes of tasks taken directly from NASA-STD-8739.8. 
  • Author Content:  "Software Assurance Products" is a list of products expected to be produced by the tasks. 
  • Author Content:  "Metrics" is a list of metrics expected to be produced by the tasks.
  • Author Content:  "Guidance" is a text content much like the Guidance in tab 3 but aimed as Software Assurance workers in the performance of their tasks. 
  • Additional Guidance is a structured section as in the tab 3 Guidance. 

2.2 Other Supplementary Materials

2.2.1 Topics

Topics are typically uniquely numbered pages . The numbering is designed to enable the easy addition of References. The numbering also allows grouping Topics into specific interest groups (Development topics, Assurance topics, etc.)

Topics have many of the same tabs as SWES but there are a few key differences: 



3. Requirements For Specific Data Items

There are a number of items in the SWEHB that authors can provide. For each item, there are specific pieces of data that the editors need in order to incorporate those items properly into the SWEHB. These items are explained below. 

3.1 Text

You can provide as much text as you want. The easiest way to supply it is in a MS Word document. Much of the formatting from Word can be dropped right into a SWEHB page. In fact, if you are modifying an existing page, just copy and page the current screen into your Word document and start editing. You can cleanup formatting issues in Word and explain what you want to go where by using colored text for you comments (image 2m19c goes here). 

Much of the bullets and numbering can also be used in Word. Headings translate well, too. Put all of your structuring into Word and it will be easy for an editor to understand. 

3.1.1 Odd Items In Copied Text 

  • Blue Superscripts in References - you may see some blue superscripts in your copied text, ex. 123. You can ignore them. They will be fixed by the editors. They come from a macro that we use to take the reader to the Resources page when you have specified a reference in your text. 

3.2 References

If you provide a reference in your text you will need to supply some data to go along with them: 

  • URL - a reliable link to the reference is necessary. If the editors don't get a good link, it cannot be provided to the reader. Just put it into the text  as a link and we can find it and use it. 
  • Title of the work - The proper title of the reference item is very helpful. If you don't supply s good title, we may use the title provided in the URL page. 
  • Citation - This is where you provide the authors, publishing date, and publisher of the material. Usually we get this from the URL. Technical papers and the like usually provide this on their cover page. It the reference is to a web site, this material comes from the initial landing page. 
  • Notes: Author Content:   This is where you can provide your reasoning for why this reference is appropriate. Is some cases you will want to direct the reader to a particular spot in the reference that is important. 

With this information the editors can put the reference into the SWEHB page and properly tag it so that readers can get to the References section on the Resources tab and click on a link that will take them to the referenced material. 

3.3