[New Best Practice Guide]: Product Website Content and Structure Practice/Guidance

[PaulMRamirez]

Checked for duplicates

Yes - I've already checked

Describe the needs

Currently there is a nice trade study from SLIM on information hosting https://nasa-ammos.github.io/slim/docs/guides/documentation/documentation-hosts/ that references Docusaurus as one option. It would be good to have a Best Practice Guide that speaks to the minimal needs one level deeper and has a template for taking something like Docusaurus one level deeper.

At a high level I'd call out some potential core components to said best practice.

1. Docs - Audience: Product User, Purpose: Understand capabilities, configurations, design
2. API - Audience: Developer, Purpose: Understand programmatic interfaces (likely can be generated)
3. Blog - Audience: User Community, Purpose: Communication
4. Main Site - Page, Audience: General, Purpose: Branding and outreach

The best practice guide could map out these core components based on a survey or summary of publications that speak to this content. It could provide guidance to the content and high level structure of these components. Moreover, it could provide pratical guidance on how to tie to together other practices suggested through SLIM (e.g. where to provide links to you community, where your releases get announced, etc. ).

A parallel effort to this could be a Docusaurus template project that brings these pieces together and builds in this one level deeper guidance and implementation. The Aerie provides a good baseline for this . I suggest that we could use MMGIS as a test case to map into a similar structure.

Some Goals:

• Minimize maintenance of documentation
• Provided branding footprint and structure for software products
• Create a shared repository that provides a faster jumping of point for new open source software
• Provide a path for folks to map existing open source software sites into

[PaulMRamirez]

@lklyne @ewferg @tariqksoliman

This is that item I've discussed with you all. Let's have our discussion here and thoughts of what could go into a Best Practice Guide and an accompanying product website template in docusaurus.

@ewferg I didn't capture your comments very well about how this may link into governance or communication mechanism very well. hopefully you can add a comment here to capture that.

@lklyne I've already found your Aerie web presence implementation was written in a way that was easy to replicate. I did wonder if there were other ideas that you had that could be done.

@tariqksoliman @ewferg each of you also mentioned linking to a showcase for said product as part of the site. @ewferg I had concerns about how one could implement that but I could see how in this content structure there could be a place for capturing public references to usage that could be community contributed (i.e. showcases).

[PaulMRamirez]

@riverma I can offer to do a docusaurus template. Not sure if I have the time to do a survey for a best practice guide. should this be broken off as a separate issue?

[tariqksoliman]

Thanks @PaulMRamirez
To reiterate some of the conversation, some of the minimal needs (which aren't always out-of-the-box) of a Docusaurus (or any other documentation host) Best Practice Guide would/could be:

• Search
• Supports demos (when possible). For instance the demo (top-left) provided here: https://nasa-ammos.github.io/LithoSphere/
• Can have swagger/API specific documentation integrated
• Can syntax-highlight code blocks

[pogi7]

@PaulMRamirez I have modeled the open source documentation that my project uses off of SLIM. New support was added for

• Offline Search (Normally search is supported by Algoria but Docusaurus has a plugin that allows for offline search)
• Typescript Support
• Versioning

I agree with @tariqksoliman post about adding integrations with search, demos, swagger/API, and syntax-highlighting for code blocks to the best practice for Docusaurus.

[rpuncel]

Adding my vote. I would also like to offer that SLIM keeps in mind for the best practice that it is common for progrmaming languages and other ecosystems to have an idiomatic documentation tool. While it makes sense that SLIM focuses on a single tool to keep scope down, I would like to see the guide include a section pointing to resources for some major idioms for each language. This could just be a "jumping off point" with links.

For example, for most Python projects, sphinx and readthedocs will often make the most sense and blend best with the community.

[riverma]

@riverma I can offer to do a docusaurus template. Not sure if I have the time to do a survey for a best practice guide. should this be broken off as a separate issue?

@PaulMRamirez great idea creating this ticket! I can certainly help out with the docuaurus template as well (lot of experience working with Docusaurus, especially via the SLIM website). One approach we could take is to provide a launching point from the proposed SLIM guide itself that lets people customize / preview a site template in their browser that they can then commit to their own respective repository. Check out the StackBlitz link within https://docusaurus.new as an example. There's also the CodeSandbox or the GitHub-tied VSCode in a browser editor which can be a launching point as well.

In terms of a survey, lets keep that as part of the scope of work for this ticket to keep things simple.

By the way, we have a number of existing SLIM tickets that might relate to this ticket. We could either link them as needed or be inspired by the contents described:

• [Improve Existing Best Practice Guide]: Documentation Organization Ref Architecture #29
• [New Process Improvement Need]: Document configuration management for open source and flight projects #56
• [Improve Existing Best Practice Guide]: Documentation Guide Additional Material #67
• [Improve Existing Best Practice Guide]: Guidance on choosing a documentation hosting solution #78
• [New Process Improvement Need]: Design System #136

[riverma]

Adding my vote. I would also like to offer that SLIM keeps in mind for the best practice that it is common for progrmaming languages and other ecosystems to have an idiomatic documentation tool. While it makes sense that SLIM focuses on a single tool to keep scope down, I would like to see the guide include a section pointing to resources for some major idioms for each language. This could just be a "jumping off point" with links.

For example, for most Python projects, sphinx and readthedocs will often make the most sense and blend best with the community.

@rpuncel - I'm curious, what makes sphinx or readthedocs more appropriate for Python projects in your mind?

[PaulMRamirez]

@pogi7 agree on offline search being needed in the default template.

@riverma thanks for linking to those issues they are definitely related here and very much useful. Is there any guidance on a single repository or separate repository for a product’s docs (e.g. http://github…/product and http://github…/product-docs)

@rpuncel for this issue I was thinking of staying with Docuaurus. I believe the template could very easily document that docs link from the site could point off to another site.

[PaulMRamirez]

@rpuncel this is also why I noted that this could break into two separate issues. One a guide and another that is the docusaurus template. I’m not quite sure what that would look like but it’s worth keeping in mind.

[lklyne]

@lklyne I've already found your Aerie web presence implementation was written in a way that was easy to replicate. I did wonder if there were other ideas that you had that could be done.

@PaulMRamirez Glad to hear its easy to replicate. I'm in full support of this effort! A couple of ideas about the public landing page aspect.

• There isn't a treatment for longer form text on the Aerie page. This might be useful for projects that want to surface a bit more information rather than linking straight to the documentation.
• Theres a bit of up front design work to create graphics to represent concepts. These are just pngs, but they could be actual screen grabs of the UI.
• I wanted to do a bit of design iteration to figure out how to make the aesthetic a bit more technical and create some different layouts for the sections. They are all pretty similar now with repeating bento grids. Having different sections that are more text heavy or just use a single graphic would be a good way to add visual interest between sections.

[PaulMRamirez]

Proposed Front Page Content for discussion:

Navigation

• Left Side:
  | Docs | API | News/Blog | About [Optional]
• Right Side:
  Github Link | Search

Main Content:

• Hero Section:
  Product tag line - one sentence description
  Product screenshot
  [Get Started Button] | [Download Now Button] | Contact link
• Customer Logos [Optional]:
  Mission/Customer logos to show a sampling of who is using the product
• Testimonials [Optional]:
  3-4 Quotes of customers to endorse the product
• Product Video [Optional]:
  1-2 minute video of the product (teaser describing product)
• Features:
  High level picture and 1 sentence for each key feature
• Get Started:
  [Optional] By User Type (e.g. for Mission Planners link to guide)
  Developers - License description and link to quick start installation
• Learn More:
  Team Communication (e.g. Slack)
  Discussion Thread (e.g. GitHub)
  News and Updates (link to Blog/News section)
• Sponsors:
  Attribution Logos
• Footer:
  Product Name and Organization
  Resources: Links to key resources for the product
  Contact Links

About Page:
Follow example such as https://sdap.apache.org/team

[rpuncel]

Adding my vote. I would also like to offer that SLIM keeps in mind for the best practice that it is common for progrmaming languages and other ecosystems to have an idiomatic documentation tool. While it makes sense that SLIM focuses on a single tool to keep scope down, I would like to see the guide include a section pointing to resources for some major idioms for each language. This could just be a "jumping off point" with links.
For example, for most Python projects, sphinx and readthedocs will often make the most sense and blend best with the community.

@rpuncel - I'm curious, what makes sphinx or readthedocs more appropriate for Python projects in your mind?

I'd use the word more "idiomatic" instead of "appropriate". There's a huge number of Python projects with documentation generated with sphinx and hosted on read the docs. Following that, there are plenty of resources focused on sphinx auto-generated documentation.

[riverma]

@PaulMRamirez - really like your draft. One suggestion is that we recommend a take-it-if-you-want-it documentation hierarchy within the "Docs" section. This ticket describes the need for that. We evaluated @Scotchester's suggestion for reviewing the https://diataxis.fr/ project, and offered a recommendation in this PR. If you like that, I can merge the PR details in to the future template.

@riverma thanks for linking to those issues they are definitely related here and very much useful. Is there any guidance on a single repository or separate repository for a product’s docs (e.g. http://github…/product and http://github…/product-docs)

I'd suggest the latter. They're more maintainable that way. We've had some real-world success with that approach here: https://github.com/unity-sds/unity-docs

Also @PaulMRamirez - SLIM has a great guide on getting started with a contribution. I think a couple codebases may be needed:

1. A fork of the SLIM repo to create an eventual PR for a new guide that contains a write-up and quickstart
2. A fork of Docusuaurs' repo repo to house the Docusaurus template project. Something like "slim-docsite-template" etc. Maybe there's a better way than creating a fork though - like keeping it simple by creating a single patch file that patches in the necessary Markdown files, config files, etc. we're proposing, on top of a fresh Docusaurus initialization? If we're moving ahead with a fork, I'd recommend publishing the new repo to NPM so that using it can be as simple as: npm init slim-docsite-template@latest or equivalent.

[PaulMRamirez]

@riverma yep I plan to create a PR for the guide for folks to iterate on.

It would not be a fork of the Docusaurus repo but rather a template project likely taking the following steps:

1. npx create-docusaurus@latest slim-docsite-template classic --typescript

2. Then remove all unnecessary content.

3. Followed by setting up the default config as well prescribed templated content and structure.

4. Installing any default plugins (e.g. local search)

5. Setting up a sample publishing flow to GitHub pages

It could be that I can set this up as a new npm repo but I’d likely need some help on that. Of course contributions would be welcomed on any of the above.

[riverma]

@riverma yep I plan to create a PR for the guide for folks to iterate on.

It would not be a fork of the Docusaurus repo but rather a template project likely taking the following steps:

1. npx create-docusaurus@latest slim-docsite-template classic --typescript
2. Then remove all unnecessary content.
3. Followed by setting up the default config as well prescribed templated content and structure.
4. Installing any default plugins (e.g. local search)
5. Setting up a sample publishing flow to GitHub pages

It could be that I can set this up as a new npm repo but I’d likely need some help on that. Of course contributions would be welcomed on any of the above.

This is great @PaulMRamirez. Thank you for your help here! This works really well. Once in a while we'd need to keep slim-docsite-template project up-to-date with respect to Docusaurus core updates: https://docusaurus.io/docs/migration

[PaulMRamirez]

Create the repository for the template website https://github.com/NASA-AMMOS/slim-docsite-template. Folks who have specific issues here that are related to the template can feel free to add stuff there. Working on an initial commit so there's something more to see there.

[riverma]

Create the repository for the template website https://github.com/NASA-AMMOS/slim-docsite-template. Folks who have specific issues here that are related to the template can feel free to add stuff there. Working on an initial commit so there's something more to see there.

Thank you @PaulMRamirez! Can you please add the repository to @NASA-AMMOS/slim-committers team? You should have perms.

[riverma]

@PaulMRamirez - FYI I'm working on this and will commit some updates to https://github.com/NASA-AMMOS/slim-docsite-template within the next week for review. We already have a potential customer (the OPERA project, CC @sjlewis-jpl) we can trial our infusion into.

[riverma]

@PaulMRamirez - I've got a working prototype website per above specs ready (see screenshot). Can you add the repo slim-docsite-template to the slim-committers team list of repos so I can push it up?