search

sensu / catalog

Monitoring as code for Sensu Go. "There's a template for that!"
8 stars 4 forks source link

Add shortcodes for standardized sections in readmes #236

Open hillaryfraley opened 2 years ago

hillaryfraley commented 2 years ago

Anthony mentioned adding structured metadata to organize the integration readmes into standardized sections that can be pulled into the docs. Since the docs use Hugo, I used the Hugo shortcode format as an example here.

I suggest standardizing the readmes into the following sections:

Section Description
Purpose Brief statement that explains what the integration does
Integration resources List of Sensu resources the integration will create or install
Supported ~Sumo Logic~ dashboards Name, link, and screenshot of ~Sumo Logic~ dashboards the integration supports
Dependencies List of prerequisites with links to any information users need before installing the integration
Setup Instructions for any configuration required for resources (should not include configuration for resources the integration creates/installs)
Metrics Table that lists metrics the integration produces, with the name, description, and tags for each metric
Events Table that lists events the integration produces, with the name and description for each metric
More information List of links to information outside the catalog readme that is likely to be relevant and helpful for people trying to use the integration

Other notes

It seems confusing to list plugins as dependencies. They aren't listed as a resource that will be installed, so users might think they have to go track down this plugin and install it separately to use the integration. We should find a better way to explain what users need to know about the plugins.

We probably need a better section descriptor for the "Setup" content. We should definitely explain that the integration itself is set up in the Catalog, and the "setup" referred to in this section is specific to non-integration resources.

The "More information" section should always include links to the Catalog docs (currently https://docs.sensu.io/sensu-go/latest/web-ui/sensu-catalog/).

jspaleta commented 2 years ago

@hillaryfraley Interesting.
When pulling into docs do you have a plan for how to handle the multiple version capability that the catalog exposes? Or are you just going to pull the main branch of the catalog repo?

Is there something we can script up and add an automated CI test that checks for README structure compliance to a docs needs pov? Not content, but just to make sure we have the correct markdown structure (the sections you want) and if possible check the hidden hugo shortcode logic is correct. When we are writing and reviewing these as markdown, we aren't going to know if we've screwed up the hugo shorttag logic even if we add it. Maybe there's a way to spin up docs-compliance linter script to run against PRs that will pass/fail structure needs from a docs pov? And some instructions on how I can test on my local machine prior to submitting the PR. Without a way to quick test the hugo specific bits, we'll never get them correct. You'll have to come back through on a 2nd pass after the fact.

Comments

Dashboards

We deliberately are leaving the dashboard section open enough so people can contribute instructions for other dashboard like grafana. We do not want to make the section SumoLogic only. We're on the hook internally for providing the SumoLogic dashboards over time as value add.. but we also want to make sure we keep a space in the README so contributors can add instructions for things like contributed and externally maintained Grafana dashboards.

Plugins

We have to list plugins somewhere because 'plugins' provide the executable commands, in the form of assets resources. And if you need to learn about all the capabilities of a command used in something like a check or handler, you have to go look at the plugin. Or if you need to file a bug or feature enhancement request.. you need the plugin repository. If dependency isn't the correct word, I'm not sure what the better word is.. but we do need to provide references back to the plugin repos for plugins used in the integration.

hillaryfraley commented 2 years ago

Jef, thank you. I don't have a plan for the integration versions and I'm not sure what is the best way to deal with that issue.

The docs site will not run locally if there's a shortcode formatting error. We also have Heroku set up to create a preview app of every sensu-docs PR, so that preview would show any errors too. But both of those things require someone (integration creator? DA? docs?) to mess around with the docs too, so maybe there's a better solution.

I'm not sure if Hugo can do things like check whether a particular page (i.e. a readme) includes all the "required" sections.

Hugo shortcodes may not be the best way to go about this... @agoddard mentioned microformats, which I think would look something like this:

<article class="h-entry">
  <h1 class="p-name">Integration Name</h1>
  <p>Published by <a class="p-author h-card" href="https://example.com">Jef Spaleta</a>
   on <time class="dt-published" datetime="2022-04-15 12:00:00"></time></p>

  <p class="p-purpose">Purpose of integration blah blah here.</p>

  <div class="e-resources">
  <h2 class="p-section-name">Integration resources</h2>
  <p>Resource 1</p>
  <p>Resource 2</p>
  </div>

  <div class="e-dashboards">
  <h2 class="p-section-name">Dashboards</h2>
  <h3 class="p-subsection-name">Dashboard 1 Name</h3>
  <p>Dashboard 1 blah blah</p>
  <h3 class="p-subsection-name">Dashboard 2 Name</h3>
  <p>Dashboard 2 blah blah</p>
  </div>
</article>

and so on.

Anthony may need to correct me here b/c I am not very familiar with microformats. Maybe microformats could be useful for sorting out the versioning question?

Thank you also for correcting my bad assumptions in my notes. I'll update the PR accordingly.

jspaleta commented 2 years ago

Quick google search lead me to this: This might be a shortcode aware markdown linter we can try to use as a CI test. I'm going to try to find time to play with this and see if it doest what I think it does. https://github.com/HitkoDev/md-shortcodes-lint/tree/master/packages/remark-hugo-lint

But in the meantime, if we started requiring specific markdown sections, would could definitely build a linter for that to ensure we have the basic markdown structure docs want to require.

calebhailey commented 2 years ago

@thoward noted that DataDog uses a CSV for this:

Compare:

hillaryfraley commented 2 years ago

I found this today: https://randomgeekery.org/post/2020/06/csv-and-data-tables-in-hugo/

jspaleta commented 2 years ago

@hillaryfraley Hey there any more discussion on your side about standardizing on the shortcodes in the readmes?

hillaryfraley commented 2 years ago

@hillaryfraley Hey there any more discussion on your side about standardizing on the shortcodes in the readmes?

Hey -- no, we haven't discussed it. Should I add it to the agenda for the next DA<>CE sync?