1. Updates to SWEHB Pages

From 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. The largest changes are when a new NPR 7150.2 is released. This will spawn a whole new SWEHB version. All changes will need to be passed through the very small team of SWEHB Editors. These editors will need very specific information from you. 

There are several groups of pages types in the SWEHB. In general, authors of new pages will be encouraged to use one of the existing page structures when adding totally new content. A structure similar to a SWE or a Topic gives plenty of leeway for authors to get their points across without going too far afield in terms of structure. Editors will be happy to discuss with you how to best organize you material to best get your point across. 

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

In general, you may make changes to the Rational, Guidance, Small Projects, Lessons Learned, and most other tabs found in the Topics. 

  • You may provide additional or changed graphic images such as photos, charts, diagrams with stick figures, or similar items. See tab 3  for details on specific data needed. 
  • You may provide tables of data or links to other SWEHB pages. 
  • You may provide References to be used in various sections See tab 3  for details on specific data needed for References.
  • You may make changes to the content of many pages in specific tabs such as Rational, Guidance, and a few others. 
  • Based on the type of material you are providing, please make it clear when you divide up the content, which headings are to be TABS and which are to be SUBHEADS WITHIN A TAB

Most of the content you will provide is best communicated in a few formats: 

  • MS Word Documents
  • MS Excel Worksheets
  • MS PowerPoint 
  • Static images such as .PNG or JPEG files
  • URLs to outside resources

. 

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 Title, 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: 

  • Structured pages such as Resources will be built by the editors. 
  • Author Content: Pages that have a specific purpose such as Lessons Learned, will be structured to be consistent with other similar pages but the content itself will be provided by you. 
  • Author Content:  The remaining tabs are for you to create and organize. Editors may suggest some restructuring of this material to give the overall structure of the Topic an appropriate balance. You don't want dozens of tabs with one small paragraph in each. You also don't want to create only one tab that is a dozen pages long. 

2.2.2 Process Asset Template

This is a very specific type of page. It is actually a Word document (or in a few cases an Excel Worksheet) containing a preformatted document prototype that a project can download, enhance, and use with a minimum of effort. Most PATs are in the form of checklists that can be used in a variety of project activities. The Requirement Mapping Matrix (in PAT-028 - NPR 7150.2D Compliance Matrix is one example of a PAT that can be downloaded and used by projects. 

PATs are typically built as a standalone document and referenced in a SWEHB page as a resource that can be used by a project. For a current list of PATs see PAT Database.

Author Content: You will provide the content of the page in the form of either MS Word or Excel Worksheet. You will control the documents themselves and provide updated documents to the editors for inclusion in SWEHB. 

2.2.3 Checklist

There are a number of checklists in D. Topics. Many have been converted to PATs. If you want to contribute a checklist for inclusion here we will need to discuss the most appropriate format for it. It should be submitted as a Word document or an Excel Worksheet. 

Author Content: You will provide the content of the page in the form of either MS Word or Excel Worksheet. You will control the documents themselves and provide updated documents to the editors for inclusion in SWEHB. 

2.2.4 Document Content Page

These pages have a specific format. Some tabs are structured. 

  1. Minimum Recommended Content - Author Content:  This is a numbered list of headings in the document. 
  2. Rationale - Author Content:  This is a text for the rationale statement.
  3. Guidance - Author Content:  This is a text for the Guidance on populating the document.
  4.  Small Projects - Author Content:  This is a text for the Small Projects statement.
  5. Resources - This is structured content for References, etc.
  6. Lessons Learned - Author Content:  This is a text for the Lessons Learned.

2.2.5 Other Unstructured Pages

There are several other groups of pages in the SWEHB. In general, authors of new pages will be encouraged to use one of the existing page structures when adding content. A structure similar to a SWE or a Topic gives plenty of leeway for authors to get their points across without going too far afield in terms of structure. Editors will be happy to discuss with you how to best organize you material to best get your point across. 

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 Images

If you want to provide an image to be included in your page, you will need to provide the following: 

  • If you have created the image in PowerPoint, please provide the PowerPoint file with the image(s). Also, provide an explanation of which images are to be included in the SWEHB page if there are multiple images in the PowerPoint. The PowerPoint is a very easy format for building images and manipulating them. They also provide a number of good formats (such as JPEG, PNG, and others) for  including the image in a SWEHB page. 
  • If you only have the image, please provide it in PNG or JPEG format. 
  • If you want to re-use an image from an existing document that we have access to (like NPR 7150.2, another NASA document, or an outside reference in the public domain, please provide detailed instructions on how to get to that reference. Include the Figure number so there is no confusion as to what image you want to use. 
  • The image will be included in the SWEHB page in an appropriate format and size that conforms to other images in SWEHB. 
  • Be careful in specifying images to ensure that it is readable and can be understood by the reader. For example: the "Flight Software Software Testing Life-Cycle" diagram in Topic 7.06 - Software Test Estimation and Testing Levels is almost unreadable due to its size. 

3.4 Tables

Tables are easy to add into SWEHB pages from Word documents, Excel worksheets, or PowerPoint files. 

  • Make sure that the heading rows or columns are clearly marked. They will be filled with Blue backgrounds in SWEHB. 
  • Make sure that the rows and columns are of appropriate sizes. They may be adjusted in SWEHB. 

3.4 Attached Word Documents

If you provide a MS Word document to be attached to a SWEHB page (such as a PAT), it may be added to the page as an attachment that can be downloaded by the reader. A thumbnail image of the document will be provided on the page so that the reader can see what the document looks like before they download it. The editors will also add a warning that the document must be downloaded before it can be used. 

You will provide the content of the page in the form of an MS Word document. You will control the versioning of the documents themselves and provide updated documents to the editors for inclusion in SWEHB. 

3.5 Attached Excel Worksheets

If you provide MS Excel Worksheet to be attached to a SWEHB page (such as a PAT), it may be added to the page as an attachment that can be downloaded by the reader. A thumbnail image of the worksheet will be provided on the page so that the reader can see what the document looks like before they download it. The editors will also add a warning that the document must be downloaded before it can be used. 

You will provide the content of the page in the form of an Excel Worksheet. You will control the versioning of the documents themselves and provide updated documents to the editors for inclusion in SWEHB.