Completing Pages site for RC

[wendellpiez]

User Story:

As an OSCAL user, I need to find information on OSCAL on the web site. For the Release Candidate, the site needs to be as good as we can make it.

Goals:

In meeting with Jim Foti (NIST) we captured the following excellent suggestions:

• All pages should have a side navigation panel for visual consistency and ease of use.
• In general, the top of the side navigation should indicate the page being shown in context, that is, within the same structure as it indicated by site navigation (top nav bar).
• Some of these pages would also benefit from navigation on the page with links to the h2 and h3 headers (there must be a Liquid filter for this).
• The "Learn More" pages are especially scant. They need examples or links to examples.
• Pages, especially time-sensitive pages such as "News", should have a line at the bottom indicating the date last modified.
• Also, these items should be reverse-chrono ordered.
• And kept up to date (we need a maintenance model).
• Search is not working on the Preview site. Maybe this needs its own Issue? Clicking the Search button results only in its disappearance.

We need to triage this set of issues, add any that are newly uncovered, and complete any that are determined to be in scope for this effort (probably most of them).

Simultaneously, we are conducting an internal review at NIST looking at all the content for accuracy and clarity.

Dependencies:

This Issue picks up from #311, which can be closed.

Additionally, these edits will be easier to make if #286 and #314 are complete and integrated.

Acceptance Criteria

1. All revisions and improvements we can make, have been made
2. We are tracking any revisions and improvements staged for later

[wendellpiez]

Comparing to our site, the USWDS demo site is interesting: https://designsystem.digital.gov/documentation/

Note:

• USWDS has no Search
• Top level nav is only one level. Lower levels are linked only from side panel navigation. Link in, and the side navigation extends (dynamically). This arrangement helps with the problem noted above, that side navigation is inconsistent and hard to trace.

[wendellpiez]

Progress March 27 2018

Having received comments from our internal review, I have made many changes to the site and have notes on more changes to be made.

These need to be captured and organized into a set of tasks and/or questions.

[iMichaela]

03/28/2019

With help from Jim Foti, @wendellpiez made initial updates. We have more to update and we will also need some input from @david-waltermire-nist. The navigation needs to be restructured. @wendellpiez and @anweiss will meet to make the changes. @wendellpiez will add the list of requirements from Jim here.

[wendellpiez]

The goals list above presents an initial punchlist of the items called out by Jim (and not yet done).

I also have a more detailed list including many potential enhancements to content. However, these also depend on changes to structure. @anweiss and I will communicate on how best to expedite this.

[wendellpiez]

Noting that today's preview has broken links on the "Community" page. These will be fixed with restructuring underway.

[wendellpiez]

Progress April 4 2019

Current preview here: http://nist-oscal.s3-website-us-east-1.amazonaws.com/

Most of the changes being tracked above have been made.

Remaining (not an exclusive list):

• Some inconsistencies between page names, headers and sidenavs to be ironed out
• Need to plan for maintenance of time-sensitive pages
  • Show dates including "last modified" date for page
  • Track in reverse-chrono order
• Search is not working; must discuss (uswds?)
• "Community" pages - they say who they are, but not what they should do or how they can help
• "Components" pages - must be more complete and tied to the actual architecture of OSCAL - how this relates to the layered schemas
• "Learn More" pages
• Schema docs - much work to do
  • Better navigation?
  • Separate remarks for JSON and XML?
  • Top-level pages for each model with strategic view (markdown, not pulled from the metaschema)

Suggest we make separate issues for these and close this one.

[brian-ruf]

4/4/2019 - @anweiss to point to instructions so he and @david-waltermire-nist can setup search on 4/5.
See #314 for other follow-up actions.

[iMichaela]

04/11/2019

NIST advised the team to embed Google analytics. Waiting for the code. Otherwise, the pages are ready for the first release followed by next editing cycle in the next Sprint.

[david-waltermire]

4-19-19

@david-waltermire-nist will verify that these are addressed in the PR and will work with @wendellpiez and @anweiss to correct any remaining issues (e.g., add google analytics). One this is done, we can close the issue.

[iMichaela]

5/2/2019

waiting for review from @david-waltermire-nist . We need to test the embedded Google analytics code.

[brian-ruf]

5/9/2019

Waiting on bug fix in #314, for acceptance of PR #326, and publication of the site to NIST pages.

[anweiss]

Hey all ... sorry I wasn't on today's status call. Let me know when you're ready to queue up #326 for merging and I'll take it out of WIP status.

[david-waltermire]

This has all been addressed in PR #326.