search

NASA-AMMOS / slim

Software Lifecycle Improvement & Modernization
https://nasa-ammos.github.io/slim/
Apache License 2.0
24 stars 9 forks source link

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

Open PaulMRamirez opened 1 month ago

PaulMRamirez commented 1 month ago

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:

PaulMRamirez commented 1 month ago

@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 commented 1 month ago

@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 commented 1 month ago

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:

pogi7 commented 1 month ago

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

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 commented 1 month ago

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 commented 1 month ago

@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:

riverma commented 1 month ago

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 commented 1 month ago

@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 commented 1 month ago

@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 commented 1 month ago

@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.

PaulMRamirez commented 1 month ago

Proposed Front Page Content for discussion:

Navigation

Main Content:

rpuncel commented 1 month ago

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 commented 1 month ago

@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 commented 1 month ago

@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 commented 3 weeks ago

@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 commented 2 weeks ago

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 commented 2 weeks ago

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.