[New Website Feature]: Simplify SLIM best practice guides

[riverma]

Checked for duplicates

Yes - I've already checked

Alternatives considered

Yes - and alternatives don't suffice

Related problems

As mentioned by @tariqksoliman et al in https://github.com/NASA-AMMOS/slim/discussions/36 as well as other discussions with folks like @darth-pr a few months back, the SLIM best practice guides are a bit complex to sift through for new folks. They have quite a few pages to go through and that adds complexity.

Moreover, the prime interest in users of SLIM so far has tended to be Starter Kits, which are a bit buried in the documentation.

Describe the feature request

Let's try and simply the organization / structure of the SLIM best practice guides.

Right now, for example the "Documentation Guide" has the following structure:

• Use Cases
• Trade Studies
• Reference Architectures
• Starter Kits

Can we simplify the above to something more interactive and use case oriented? RETYPE has a feature called "stacked panels" which we could leverage as a set of initial questions for pointing people to specific resources we're offering.

Per @tariqksoliman's suggestion, I'm thinking we simplify the whole best practice guide structure to the following only:

1. A set of stacked panels for resources people might be interested in. For example: "I'm looking for templates", or "I'm looking for tools", etc. These panel provide a set of links to resources in step 2 below.
2. A single page with all resources provided and anchor-linked for quick reference

Open to other ideas!

[riverma]

Something like this, where to top expandable area would link to resources described in more detail at the bottom:

We'd have to of course adjust the contents based on each "guide".

[riverma]

Thoughts @jpl-jengelke @jpl-btlunsfo @tariqksoliman @darth-pr?

[galenatjpl]

I would be good to have a video at the top of the guide, so that new projects can get a quick overview in video form.

[riverma]

That's a great idea @galenatjpl - to have video introductions in general. In fact, you made me think that the front page of SLIM (https://nasa-ammos.github.io/slim/) currently explains more about SLIM than points people to the key best practice guides. Maybe a video or quick pointer sooner on the main page would help.

[riverma]

New idea

What about a faceted search approach where tags are utilized to label and organize specific process improvement solutions?

Pros:

• Scalable
• Quick access to specific process improvement solutions

Cons:

• Less room for hierarchy organization of process improvement content

Example framework

https://github.com/itemsapi/itemsjs (client-side only!)

[riverma]

I've performed some trade-analysis of key features desired and found the following:

RETYPE

• [X] Markdown support
• [X] Pre-built static site that "just works" and generally looks as good as the existing SLIM website
• [ ] Support for creating a faceted search experience
• [ ] Support for a community-edited master file that details metadata about starter kits, and that can be used to build a faceted search experience
• [ ] Support future custom code to create any kind of interactive UI experience
• [X] Search box
• [ ] Community plugins
• [X] Rich media
• [X] Mermaid support
• [ ] No limit to the number of total pages
• [ ] Blogging support
• [X] GitHub Pages hosting

ItemJS

• [ ] Markdown support
• [X] Pre-built static site that "just works" and generally looks as good as the existing SLIM website
• [X] Support for creating a faceted search experience
• [X] Support for a community-edited master file that details metadata about starter kits, and that can be used to build a faceted search experience
• [X] Support future custom code to create any kind of interactive UI experience
• [X] Search box
• [ ] Community plugins
• [ ] Rich media
• [ ] Mermaid support
• [X] No limit to the number of total pages
• [ ] Blogging support
• [X] GitHub Pages hosting

Docusaurus

• [X] Markdown support
• [X] Pre-built static site that "just works" and generally looks as good as the existing SLIM website
• [X] Support for creating a faceted search experience (Requires coding)
• [X] Support for a community-edited master file that details metadata about starter kits, and that can be used to build a faceted search experience (Requires coding)
• [X] Support future custom code to create any kind of interactive UI experience
• [X] Search box
• [X] Community plugins
• [X] Rich media
• [X] Mermaid support
• [X] No limit to the number of total pages
• [X] Blogging support
• [X] GitHub Pages hosting

GitBook

• [X] Markdown support
• [X] Pre-built static site that "just works" and generally looks as good as the existing SLIM website
• [ ] Support for creating a faceted search experience
• [ ] Support for a community-edited master file that details metadata about starter kits, and that can be used to build a faceted search experience
• [ ] Support future custom code to create any kind of interactive UI experience
• [X] Search box
• [X] Community plugins
• [X] Rich media
• [X] Mermaid support
• [X] No limit to the number of total pages
• [X] Blogging support
• [ ] GitHub Pages hosting

Based on the above - I'd recommend we consider Docusaurus and propose a PR to draft a vision of the site for community review.