Content updates needed on this page: 

1. Full cleanup in 2 - 5

 1. Introduction

The Software Engineering Handbook (SWEHB) web site was started in 2010. It was built on a Confluence Wiki platform at GSFC. There were a number of plugins and macro packages used to build out the rich capability in the product. It was initially published as an internal NASA site. 

The design accounted for only one version, the most current at the time, would be published in space “7150”. Fundamental design changes were necessary to accommodate multiple versions of the Handbook in the SWEHB site.

• In 2017 the second version of SWEHB was born. It was based on NPR7150.2B in the space “SWEHBVB”.
• In 2018 work began on a third version of the SWEHB in space “SWEHBVC”.
• The most current version is based on NPR7150.2D and is in space “SWEHBVD”.
• The next version will be based on NPR 7150.2E and be included in space “SWEHBVE”.

1.1 Additional documentation

The documentation includes details about how the SWEHB is built and maintained. Style Guides for certain types of pages are included as pages under this page. 

 1.2 User Access

Access to the SWEHB is granted to anyone who can get to it through the world wide web through the URL: SWEHB.NASA.GOV.

It is not necessary to log in to Confluence to use the SWEHB. Users may browse the content as Anonymous users. This access to content allows users to view content and download attachments.

Editing and content creation is restricted to a small number of developers and curators who have Confluence logins and are in the appropriate group of editors. 

 2. Architecture

 3. SWEHB Style Guide

For details see SWEHBDOC Basic Style Guide. 

 4. Features and Editor Tools and Tips

For details see: 

SWEHBDOC Features And Tools - 

SWEHBDOC Editor Tools and Tips - 

5. SWEHB Maintenance

For details on regular maintenance activities see SWEHBDOC Maintenance. 

5.1 Production and Staging Sites

The copy of the SWEHB on the Production server is where all content maintenance is performed. When testing of Confluence and platform level software releases need to be performed, a copy of the production content is put onto the Staging server. Testing of the platform software changes is then done to make sure there are no regression issues between the software running on Production and Staging. If there are no issues, Production software may be updated. More details on these spaces is available in the SWEHBDOC Architecture page. 

5.2 Backup and Restore Of Spaces

IT is responsible for all backups and restoring of spaces. 

6. How Do I ...

This section covers some typical scenarios in SWEHB maintenance. Each describes the problem and provides links to SWEHBDOC pages where help can be found. 

6.1 Make Content Corrections In A Page?

Simple content corrections on a page may be done using the editor. 

1. When you are viewing the page, click on the Edit command in the bar just above the page Title. This will open the page in the WYSIWYG editor. 
2. You will see "frames" representing macros in the page. In the "tabsetup" frame you will see additional "Div" frames. These contain the content organized in a fashion very similar to a MS Word document with subheadings. Scroll down to the text you want to change and make the edits, adds, deletes, changes. 
3. Use the styles in the editor menu bar (dropdown menu starts with "Paragraph") if you want to convert a line to a header style.  
4. If you want to leave a note in the Page History Comments regarding what changes you made, put a short description in the "What did you change?" box at the bottom of the editor.
5. If you want to Preview the page in the editor, be aware that it will not be displayed in a tabbed format. 
6. Be sure to Save your changes. 
7. View your changes to be sure that everything looks correct. 

6.2 Reorganize Content In A Page?

Larger edits require a little more planning. You can copy and paste in the editor just like you do in MS Word. The same keyboard shortcuts work (see SWEHBDOC Keyboard Shortcuts). 

You can move content between tabs easily. Just be sure that you are taking these actions within the correct DIVs. You cannot make a selection for a copy across Div boundaries - you will end up selecting the whole DIV. 

Be sure to Save your changes and view your changes to be sure that everything looks correct.

6.3 Add Or Change a Reference In A Page?

 For full details on References, see the page SWEHBDOC References in SWEHB. 

The page SWEHBDOC Add A Reference To A Page provides details for several scenarios regarding references on SWEHB pages. 

6.4 Add Or Change Tabs In A Page? 

This is covered in detail in the page SWEHBDOC Tabs In SWEHB Pages. The page details adding the macro to a new page as well as adding tabs and moving things around on a page. 

6.5 Add Or Change A Blog Post?

 Detailed instructions on Blog Posts are in the SWEHBDOC Blogs In SWEHB page. It covers

• The history of Blogs in SWEHB, 
• Creating a Blog Post,
• Publishing it to the Intro page (using the "swehb" label),
• Viewing the history of all blogs entries.

6.6 Fix A Hopelessly Messed Up Page?

The safety-net for this situation is the Page History. if is in the dropdown menu (the little "..." on the command bar above the page title). When you click on Page History, you will see a history of every saved version of the page since it was created. You may view old pages (open in a different tab), or compare two versions. 

If you Restore to an earlier version, you wipe out the versions that followed the restored version. This allows you to get back to a good looking page and them carefully move forward with your changes again. 

6.7 Create A New SWE or Topic Page

The instructions for creating each of these page types is in the SWEHBDOC Basic Style Guide. 

• Tab 4 goes into great detail on creating a requirements page (SWE or HR). 
• Tab 5 goes into great detail on creating a topic page. 

Incorporating it into the appropriate B. Institutional Requirements, C. Project Software Requirements, or D. Topics pages is a matter of looking at where other similar pages are located and inserting it into the proper table. 

6.8 Update Descriptions Of A Topics Page in D. Topics 

The details of handling Excerpts and the Excerpt-Include are covered in SWEHBDOC Features And Tools in Tab 10 - Excerpt and Include Macros. 

There is a detailed example using topic 8.30 from the D. Topics page. 

6.9 Hide Pages or Unhide Pages 

6.9.1 Hide or Unhide Whole Pages

Hiding and unhiding pages can be done with permissions but that method is not recommended because pages can get lost if an editor goes away or doesn't remember what was done with the page. 

The cleanest way to hide a page is to move it (using the pagetree) into the Protected Area. Just create a page in the protected area for your hidden pages and drag / drop the page to be hidden into your hiding place. 

It is a very convenient feature of Confluence that hidden pages cannot be viewed or even discovered in a search by a user that doesn't have permission to edit pages. 

6.9.2 Hide Parts Of A Page

This is done in almost all pages. You will find a set of macros near the top of a page or in the References section of the Resources tab, that implement the hiding of some content that only editors need to see. Open any SWE or topic page and look for: 

• Show If macro with a parameter spacePermission = edit
• Panel macro with a title "Visible to Editors Only"
• Expand macro - this keeps the clutter minimized until the editor wants to expand it and look at the content. 

It shows up at the top of the page in a red panel box with the title displayed and a link for "Click here to expand ..."

You can use this technique anywhere in a page where you want to put comments to editors but not want users to see it. 

6.10 Check Status Of SWEHB - Daily Health Check

The daily checks I have been running are detailed in SWEHBDOC Maintenance, Tab 2 - Daily Healthcheck. 

There is a Healthcheck page in each version of SWEHB. Links to these pages are in the Daily Healthcheck tab. Viewing a Healthcheck page gives you a set of tabs to look at. Each tab exercises a particular macro and you can tell if there is a problem by following the text on the Healthcheck tab. 

There is also a section in that tab listing all the pages I check on a daily basis. There is an explanation next to each link describing what I look for on the page. 

6.11 Practice Using The Editor

You may practice using the editor and doing most of the things in the documentation by opening pages in the SWEHBVE. The main pages for the SWEHBVE are there. There is also a branch called "Practice Pages" which has copies of several SWEs and Topics that can be used for practicing making changes without hurting anything. 

An item in,  SWEHBDOC - New Version of SWEHB, in the checklist advises deleting the Practice pages when you are done them so they won't interfere with the copying of SWE Pages and Topics Pages from SWEHBVD to SWEHBVE.