search

influxdata / community-templates

InfluxDB Community Templates: Quickly collect & analyze time series data from a range of sources: Kubernetes, MySQL, Postgres, AWS, Nginx, Jenkins, and more.
https://www.influxdata.com/products/influxdb-templates/gallery/
Apache License 2.0
351 stars 157 forks source link

Make readme files follow a consistent format #171

Closed hoorayimhelping closed 4 years ago

hoorayimhelping commented 4 years ago

Background

The UI is only concerned with displaying readme data that is relevant to users of the UI.

Acceptance Criteria:

- All readmes are lowercased: readme.md ~README.md~ ~readme.MD~ ~README.MD~ - All readmes have a section titled ## UI Installation Instructions (or something similarly titled). The UI will greedily render all content that follows this header. Any instructions relevant to cloud installations, including telegraf installation instructions so go here. Some readmes might need to have their content restructured to make this more usable. - All readmes have a section under the ## UI Installation Instructions (or something similarly titled) have a portion that the user can copy and paste directly into the UI to install that template.

mhall119 commented 4 years ago

@hoorayimhelping:

  1. Templates already have a standard section called ## Setup Instructions that contain info on how to install Telegraf, supporting scripts and 3rd party services. These steps should be identical for both GUI and CLI installed templates, could we use that section instead of creating a new one?

  2. I'm unclear what copy and paste instructions would go in this section, since the UI won't display it until the user has already copy and pasted the template URL into the UI.

hoorayimhelping commented 4 years ago

@mhall119

  1. using ## Setup Instructions works for me.
  2. Absolutely correct. The suggestion to copy something from the readme into the UI is for users who are browsing the community templates and see one they like and want to install and are about to go back to the UI. The intent is to remove a bit of the ambiguity around "what am I supposed to put into the UI." @bpalani anything I'm missing?
mhall119 commented 4 years ago

@hoorayimhelping okay, so for #2 if I just add something to ## Quick Install at the top of the readme that says something like: Copy this URL into the InfluxDB UI: <url to manifest> would that work for you and @bpalani ?

bpalani commented 4 years ago

@mhall119 - yes I think I like the idea of adding UI instructions under ## Quick Install. Also there may be some additional steps required to complete the template install process (e.g. signing up for 3rd party service like Quandl) which should also be added under that section so that when users come back to the UI, they can see that under the Readme tab.

mhall119 commented 4 years ago

@bpalani all of those additional instructions should already be in the ## Setup Instructions section, and will be the same for CLI and UI installs

bpalani commented 4 years ago

@hoorayimhelping - are you able to get the additional instructions from Setup Instructions to show in the Readme tab of the UI?

hoorayimhelping commented 4 years ago

@bpalani i'm planning on doing a simple parse of the readme file and discarding everything before ## Setup Instructions

The UI will greedily render all content that follows this header. Any instructions relevant to cloud installations, including telegraf installation instructions so [sic] go here. Some readmes might need to have their content restructured to make this more usable.

mhall119 commented 4 years ago

Every template (except downsampling) has been updated to have: