riverma commented 10 months ago

Checked for duplicates

Yes - I've already checked

Alternatives considered

Yes - and alternatives don't suffice

Describe the feature request

Let's come up with a standard template for our SLIM guides that we can use for both future contributors to follow as well as for us to rewrite existing guides for.

Some of the key things I think are needed are:

A very short description of the improvement being presented
Explanation of the use cases or problems being solved
Quick access to use the solution if the reader doesn't want to read much and just get going
Step-by-step directions (preferably with imagery) for how to get going with the solution
Acknowledgements
Authorship
Mentioning that the guide can be improved further by the reader via soliciting contributions
```
### Tasks
```
[x] Design a draft template
[x] Get feedback from the community and finalize template
[x] Document how to use the template in the contribution guide of the website
[x] Apply template to existing guides

riverma commented 10 months ago

@NASA-AMMOS/slim-tsc - thoughts on the below template? Are we missing anything or any suggestions? Please take a look at our current guides to see applicability.

---- Start Markdown Rendering Below ----

Title Goes Here

One sentence description of your process improvement solution / proposed standard.

Introduction

Background: A longer description of the problem you aim to solve and your solution. Talk about the background of why this is needed, what kind of benefits the user might enjoy, and any other background information that may be useful for the reader.

Use Cases:

A list of the types of use cases where your process improvement solution will shine
e.g. Making code repository README's consistent for internal and external contributors

Prerequisites

List any software, hardware, or skills required to utilize the solution.

Prerequisite 1
Prerequisite 2
...

Quick Start

Link to Process Improvement Solution (template/code sample/tool/etc.)

A brief description of what the link provides, e.g., "Click the link above to access the full template for the README.md file."

Step-by-Step Guide

Step 1: Brief description of the step.
Step 2: Brief description of the step.
...

Credits

Authorship:

List of contributing authors of this write-up who actually wrote words. Link to GitHub profiles if available, e.g. Bugs Bunny

Acknowledgements:

Source/Organization 1 that inspired the solution or was adapted from
Source/Organization 2 that inspired the solution or was adapted from
...

Feedback and Contributions

We welcome feedback and contributions to help improve and grow this page. Please see our contribution guidelines.

---- End Markdown Rendering ----

---- Start Markdown Code Below ----

# _Title Goes Here_

<pre align="center">One sentence description of your process improvement solution / proposed standard.</pre>

## Introduction

**Background**: _A longer description of the problem you aim to solve and your solution. Talk about the background of why this is needed, what kind of benefits the user might enjoy, and any other background information that may be useful for the reader._

**Use Cases**:
- _A list of the types of use cases where your process improvement solution will shine_
- _e.g. Making code repository README's consistent for internal and external contributors_

---

## Prerequisites
_List any software, hardware, or skills required to utilize the solution._

* Prerequisite 1
* Prerequisite 2
* ...

---

## Quick Start
**[Link to Process Improvement Solution (template/code sample/tool/etc.)](#)**

_A brief description of what the link provides, e.g., "Click the link above to access the full template for the README.md file."_

---

## Step-by-Step Guide

1. **Step 1**: _Brief description of the step._
![Optional Image for Step 1](imageURL_for_step1)

2. **Step 2**: _Brief description of the step._
![Optional Image for Step 2](imageURL_for_step2)

3. ...

---

## Credits 

**Authorship**:
- _List of contributing authors of this write-up who actually wrote words. Link to GitHub profiles if available, e.g. [Bugs Bunny](https://www.github.com/bbuny573429)_

**Acknowledgements**:
* Source/Organization 1 that inspired the solution or was adapted from 
* Source/Organization 2 that inspired the solution or was adapted from 
* ...

---

## Feedback and Contributions

We welcome feedback and contributions to help improve and grow this page. Please see our [contribution guidelines](https://nasa-ammos.github.io/slim/docs/contribute/contributing/).

---- End Markdown Code ----

jl-0 commented 9 months ago

This is pretty good. I think this could cover everything, but I did wonder if the following might be their own sections. The information here could easily fit in the present sections but perhaps calling some of them out would keep things more consistent.

Expected Outcome
Required Customization / Tailoring
Common Pitfalls, FAQ (not sure on name but a section saying the common issues problems you might run into)

galenatjpl commented 9 months ago

Hi Rishi,

This looks great to me! The real issue I see is that most developers/issue-creators never go to this level of detail. I'm wondering if we should simplify it a bit, to avoid the problem of overwhelm-paralysis? If this is intended for internal SLIM folks to use, then I think it's okay. If it's intended for all projects, then maybe it's a bit much? But then again, I do agree being detailed and inclusive of all relevant things is a good thing.

UPDATE: After reading the SLIM guides doc: https://nasa-ammos.github.io/slim/docs/guides/search/ the above actually makes sense to me. I approve of this, and @jl-0 's comments above are also good ideas.

jpl-jengelke commented 9 months ago

Agreement with the layout. Per @jl-0 's comment I'm not sure we need an expected outcome section as that should be implicit in the title and stated in the subheading right below it. Instead, the template could state in the subhead, One sentence description and expected outcome of this process improvement standard.

A small (no more than 3) bullet point list could be provided under `Step-by-Step Guide' to identify required customizations, but I am not sure that's necessary.

I think the common pitfalls, FAQ are more appropriate in their own section outside the template, perhaps even in the discussion board.

riverma commented 9 months ago

Thank you for the feedback @jl-0 @galenatjpl @jpl-jengelke. Much appreciated. I've added some of @jl-0's suggestions to the template (Introduction->Background). I also really like the idea of a FAQ section that can be iterated and augmented over time - that's already part of our README template recommendations, and we might as well use it here too. Agree with @jpl-jengelke - I think the required customizations is basically the Step-by-Step Guide section.

Some adjustments below. I'll look to open a PR for this soon so we can get it going!

# _Title Goes Here_

<pre align="center">One sentence description of your best practice solution.</pre>

## Introduction

**Background**: _A longer description of the problem you aim to solve and your solution. Talk about the background of why this is needed, what kind of benefits the user might enjoy, and any other background information that may be useful for the reader. Additionally, talk about the expected outcome the user can expect in implementing your solution._

**Use Cases**:
- _A list of the types of use cases where your process improvement solution will shine_
- _e.g. Making code repository README's consistent for internal and external contributors_

---

## Prerequisites
_List any software, hardware, or skills required to utilize the solution._

* Prerequisite 1
* Prerequisite 2
* ...

---

## Quick Start
**[Link to Process Improvement Solution (template/code sample/tool/etc.)](#)**

_A brief description of what the link provides, e.g., "Click the link above to access the full template for the README.md file."_

---

## Step-by-Step Guide

1. **Step 1**: _Brief description of the step._
![Optional Image for Step 1](imageURL_for_step1)

2. **Step 2**: _Brief description of the step._
![Optional Image for Step 2](imageURL_for_step2)

3. ...

---

## Frequently Asked Questions (FAQ)

- Q: Example question relevant to this guide
- A: Example answer to the question

---

## Credits 

**Authorship**:
- _List of contributing authors of this write-up who actually wrote words. Link to GitHub profiles if available, e.g. [Bugs Bunny](https://www.github.com/bbuny573429)_

**Acknowledgements**:
* Source/Organization 1 that inspired the solution or was adapted from 
* Source/Organization 2 that inspired the solution or was adapted from 
* ...

---

## Feedback and Contributions

We welcome feedback and contributions to help improve and grow this page. Please see our [contribution guidelines](https://nasa-ammos.github.io/slim/docs/contribute/contributing/).

stirlingalgermissen commented 9 months ago

Some thoughts -

A table of contents would be nice. This is usually the first thing I look for on a GH page so I can get to the area I need additional information on
Step-by-Step Guide - for what? Build, run, deploy, adapt? Perhaps we can make this more specific or break it up
It seems we'd want to include a link to the license page
Where do CI/CD badges and an application icon go? I have a personal style preference for centering the application title and not using a code block for the one sentence description

Overall it looks good. I think creating example page for an existing JPL GH project would be a useful step to add to this issue so we can see the template in action. We could update https://github.jpl.nasa.gov/drewm/srl-idps-airflow-prototype as it is based on a SLIM template already

riverma commented 8 months ago

Hi @stirlingalgermissen - thanks for your comments! Just to clarify - this “template” is independent of the SLIM README template. The intention of this template is to standardize the written SLIM Guides themselves, not specifically to do with software repositories.

I like your idea for a TOC!

riverma commented 5 months ago

Progress: all existing SLIM pages except the following two have the new templates installed / applied:

However, since we have tickets already available for the above two (#120, #123), let's go ahead and close this ticket.

NASA-AMMOS / slim

[New Website Feature]: Design a standard template for SLIM guides #101