Documentation generation and usability

[riverma]

Had a chat with @tariqksoliman from PDS Imaging (among other projects) on possible new contributions to SLIM of:

• Guides & trade-studies on static site generators
• Usability improvements for SLIM's website

@tariqksoliman - curious about your thoughts on the above (or others!) to get a discussion started on these important ideas! Some questions for you:

1. Were you thinking of "static site generators" in the context of project websites? Or more documentation websites? Both?
2. Which kinds of static site generator tools do you have in mind? Note in our SLIM Documentation Best Practice Guide use cases document (see visualization), we have some documentation hosting tools already listed (see trade study as well). We have an unfilled section for website platforms that could be more relevant for what you're thinking?
3. What sort of usability improvements (or needs) do you think the SLIM website could use?

[tariqksoliman]

1

• I was primarily referring to static sites to document usage (and/or provide an online demo if feasible). Recommending static site generators for/as the project itself is probably out of SLIM's scope.

2

• A lot of this depends on project size, budget, type and audience of course. A project that's a library of a few commands or functions with a few arguments almost certainly should not waste time setting up any sort of usage documentation site and just use a readme.md. However a project that's a single React component should almost always have an online demo of it (perhaps using storybook) otherwise it'll pretty much be ignored.

• Your list so far is great. I've used Jekyll-based gitpages sites before for documentation (through templates). They're probably simpler than the alternatives but can allow for full control.

3

• The mind-maps can be a bit overwhelming. Perhaps the SLIM website could (in addition) be, say, a 20 part questionnaire (or just a form). Users answer each question and at the end they are given a list of the top recommendations for each part of their lifecycle. It then also gives or points to the closest matching starter kits (or full project starter kits).

• I know it's all still in the works too but the trade studies should each have a clear and recommended best workflow/software (and maybe show at most the two runner-ups (the reasonings involved and full trade study can just be a link)).

• It may be a good idea to make the SLIM site as slim/minimal as possible. For instance in the README starter kit:

To leverage this template, make sure to do the following:

1. Talk with your team about leveraging this template, and seek wide agreement before you adopt
2. Copy the template text, and place in a file within your repository called README.md
3. Search and replace the [INSERT ... text within the file with specifics for your project
4. Add a link to the CONTRIBUTING.md to your README.md file within the Contributing section

This starter kit template was developed by evaluating best README.md practices in the following organizations:

NASA-AMMOS
ReactJS
VueJS
Apache Kafka

This whole section isn't that important. All items in the list are obvious and can be explained in-line in the template if not already. Reasonings for why something was chosen should probably always be secondary/hidden/on some ancillary page -- assume that readers already trust us.

[riverma]

Hey @tariqksoliman - thanks for the thoughts! Some responses.

1

* I was primarily referring to static sites to document usage (and/or provide an online demo if feasible). Recommending static site generators for/as the project itself is probably out of SLIM's scope.

Static site generators for document usage of UI components or usage for any kind of software? I'm thinking of APIs as another artifact. What other categories are you thinking, if any?

Also - I don't think project websites are necessarily out-of-scope. Complex sites with fancy features and data portals yes, but simple static sites to convey an introduction to the software in a non-developer language sense (where the developer-centric language is already covered by the docs site) could be a great standard to promote. Very few software projects in the SLIM community think about an intro site from what I've seen. Something like the simplicity of https://kafka.apache.org/. Your recommendations for simple static sites for this purpose would be really helpful!

2

* A lot of this depends on project size, budget, type and audience of course. A project that's a library of a few commands or functions with a few arguments almost certainly should not waste time setting up any sort of usage documentation site and just use a readme.md. However a project that's a single React component should almost always have an online demo of it (perhaps using [storybook](https://storybook.js.org/)) otherwise it'll pretty much be ignored.

Agree with the cost / benefit ratio here.

* Your list so far is great. I've used Jekyll-based gitpages sites before for documentation (through templates). They're probably simpler than the alternatives but can allow for full control.

Interesting - the tools I listed (apart from the API documentation generators) are pretty general site generators, and not necessarily customized for "usage documentation". So assuming we'd recommend Jekyll-based site generators, what do you think we should offer to help customize a static-site generator to support "usage documentation"?

3

* The mind-maps can be a bit overwhelming. Perhaps the SLIM website could (in addition) be, say, a 20 part questionnaire (or just a form). Users answer each question and at the end they are given a list of the top recommendations for each part of their lifecycle. It then also gives or points to the closest matching starter kits (or full project starter kits).

Ah yes - great idea! I really like this. @darth-pr has a similar suggestion a few months ago as well.

One issue is that the SLIM website is heavily markdown based, leveraging https://retype.com/, which limits fancy web development. That being said, fancy stuff can be done within HTML / JS / CSS static files, but the interaction between the RETYPE components and the HTML is not clear to me, other than through embedding the latter in the former.

I wonder if a questionnaire structure can be formulated through Markdown?

* I know it's all still in the works too but the trade studies should each have a clear and recommended best workflow/software (and maybe show at most the two runner-ups (the reasonings involved and full trade study can just be a link)).

Interesting idea - I like that a lot. I'm also not quite happy with the trade study table format, its hard to read (example). I was thinking it would be better to flatten the table into a vertical list. Something akin to the simple look/feel of Jamstack's site generator list might be helpful. I'm not clear on the benefits of detailed trade-study analysis versus just pointing people to tools to investigate further for themselves. Something to think about.

* It may be a good idea to make the SLIM site as slim/minimal as possible. For instance in the README starter kit:

To leverage this template, make sure to do the following:

1. Talk with your team about leveraging this template, and seek wide agreement before you adopt
2. Copy the template text, and place in a file within your repository called README.md
3. Search and replace the [INSERT ... text within the file with specifics for your project
4. Add a link to the CONTRIBUTING.md to your README.md file within the Contributing section

This starter kit template was developed by evaluating best README.md practices in the following organizations:

NASA-AMMOS
ReactJS
VueJS
Apache Kafka

This whole section isn't that important. All items in the list are obvious and can be explained in-line in the template if not already.

Maybe there's a less verbose way to explain this? Perhaps visually through a diagram? I worry if steps aren't laid out for some users then they won't enact changes in a way that would stick well with their projects (i.e. step 1 and 4). Some steps (like step 3) are dependent on the starter kit in question, and would need to be different for different starter kits.

Reasonings for why something was chosen should probably always be secondary/hidden/on some ancillary page -- assume that readers already trust us.

That's fair. That list was more about giving credit than justification. Do you have ideas on better ways to give credit?

[Scotchester]

I know it's all still in the works too but the trade studies should each have a clear and recommended best workflow/software (and maybe show at most the two runner-ups (the reasonings involved and full trade study can just be a link)).

I'm not sure if trying to recommend a single best choice (even with a couple runners-up) is a good idea. Software development teams at JPL/NASA (and whomever else we may be interested in this initiative in the future) are very diverse, and the "best" choice for something like a documentation site will be dependent on a lot of factors, but especially (in my mind): the team's familiarity with the languages/frameworks it employs, and the prevalence of the tool within the dev communities they are a part of.

For example, I'm a part of the JPL DesignLab Web Design & Development team; we work primarily in Python and Nuxt/Vue. As a result, our documentation (beyond READMEs) tends to be done with MkDocs and Storybook, some of the most popular tools in those domains. We would likely not want to dive into any of the top three candidates on that Jamstack.org page because they use technologies we're not as familiar with.

I think the idea of the massive trade study comparison chart could be a good one to help direct teams to the right solution, if they are unsure which way to go. If you made it full width and enabled column sorting and filtering (no clue how reasonable that is in the context of Retype), it could be a great tool for zeroing in on the right solution for a team. That said, I also fear it would be really hard to keep comprehensive and up-to-date. (Compare again with the eye-popping number of tools listed on the Jamstack.org page.) I would respectfully question whether it's a good use of (y)our time to try and provide this data.

[riverma]

Thanks for your comments @Scotchester! Appreciate your views and insights. I think you're spot on - there's costs and benefits to recommendations, and its a lot of work to do these trade studies.

It might be helpful to point out the way SLIM is governed to be community driven. If you take a look at our Community Members section of our front page, you'll see that there are a select set of projects that are considered "community members". These are the projects (or their reps) that tell us which process improvement use cases are ranked most highly in terms of their needs, and which sub-selection of tools may be most compatible with their existing software ecosystems. Thus, we're not necessarily trying to do a full comprehensive trade-study of every possible use case, but instead we try to pursue use cases that have real-world impact on community member projects and seek cross-cutting solutions between member projects. If your project (or any of @tariqksoliman's) are interested in joining as community members, then please let me know. Our hope is that community member projects' developers can also be contributors! Though this isn't a requirement.

[jpl-jengelke]

Thanks @tariqksoliman and @Scotchester. We're trying to make the site as lean as possible. Clearly verbosity does not lend itself to quick adoption. I have taken a look at Jamstack and will research markdown solutions for surveys.

[riverma]

@tariqksoliman - I'm thinking in the least, one action item from this discussion is that I could create a ticket for obvious usability improvements to the SLIM website. Would you be able to help me fill out the checklist of needed modifications in such a ticket - from your perspective? :)