Giters

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.

Home Page:https://www.influxdata.com/products/influxdb-templates/gallery/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Make readme files follow a consistent format

hoorayimhelping opened this issue · comments

commented

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.

commented

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

commented

@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?
commented

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

commented

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

commented

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

commented

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

commented

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

commented

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

  • A ### Quick Install section at the top
  • An #### InfluxDB UI subsection of Quick Install with instructions to copy the manifest URL into the UI
  • A ## Setup Instructions section with post-install instructions