Docs: updates for file-based menu (#28500)

* initial * cleanup * remove bad aliases * cleanup, fix links * add docs-file-based-command * update docs * update readme * fix broken links * fix spelling Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>
2020-11-09 12:26:49 -08:00
parent a7e092f243
commit abee02dbcd
271 changed files with 260 additions and 1266 deletions
@@ -1,9 +1,6 @@
 +++
 title = "Best practices"
 description = "Best practices for working with Grafana"
-type = "docs"
-[menu.docs]
-identifier = "best-practices"
 weight = 20
 +++

@@ -15,5 +12,5 @@ This section provides information about best practices for intermediate Grafana
 - [Best practices for managing dashboards]({{< relref "best-practices-for-managing-dashboards" >}})
 - [Common observability strategies]({{< relref "common-observability-strategies" >}})
 - [Dashboard management maturity model]({{< relref "dashboard-management-maturity-levels" >}})
-  
+
  <!-- BEGIN Optimal Workshop Intercept Snippet --><div id='owInviteSnippet' style='position:fixed;right:20px;bottom:20px;width:280px;padding:20px;margin:0;border-radius:6px;background:#1857B8;color:#F7F8FA;text-align:left;z-index:2200000000;opacity:0;transition:opacity 500ms;-webkit-transition:opacity 500ms;display:none;'><div id='owInviteMessage' style='padding:0;margin:0 0 20px 0;font-size:16px;'>Got a spare two and a half minutes to help us improve the docs?</div><a id='owInviteOk' href='https://Grafana.optimalworkshop.com/questions/grafana-docs?tag=docs&utm_medium=intercept' onclick='this.parentNode.style.display="none";' target='_blank' style='color:#F7FAFF;font-size:16px;font-weight:bold;text-decoration:underline;'>Yes, I&#x27;ll help</a><a id='owInviteCancel' href='javascript:void(0)' onclick='this.parentNode.style.display="none";' style='color:#F7F8FA;font-size:14px;text-decoration:underline;float:right;'>Close</a></div><script>var owOnload=function(){if(-1==document.cookie.indexOf('ow-intercept-quiz-4ior230e')){var o=new XMLHttpRequest;o.onloadend=function(){try{var o=document.getElementById('owInviteSnippet');var date=new Date();date.setMonth(date.getMonth()+1);this.response&&JSON.parse(this.response).active===!0&&(document.cookie='ow-intercept-quiz-4ior230e=Done;path=/;expires='+date.toUTCString()+';',setTimeout(function(){o.style.display='block',o.style.opacity=1},2e3))}catch(e){}},o.open('POST','https://app.optimalworkshop.com/survey_status/questions/4ior230e/active'),o.send()}};if(window.addEventListener){window.addEventListener('load',function(){owOnload();});}else if(window.attachEvent){window.attachEvent('onload',function(){owOnload();});}</script><!-- END Optimal Workshop snippet -->
@@ -1,10 +1,6 @@
 +++
 title = "Best practices for creating dashboards"
 description = "Best practices for creating dashboards in Grafana"
-type = "docs"
-[menu.docs]
-identifier = "best-practices-for-creating-dashboards"
-parent = "best-practices"
 weight = 100
 +++

@@ -49,7 +45,7 @@ Once you have a strategy or design guidelines, write them down to help maintain
 - If you create many related dashboards, think about how to cross-reference them for easy navigation. Refer to [Best practices for managing dashboards]({{< relref "best-practices-for-managing-dashboards.md" >}}) for more information.
 - Grafana retrieves data from a data source. A basic understanding of [data sources]({{< relref "../datasources/_index.md" >}}) in general and your specific is important.
 - Avoid unnecessary dashboard refreshing to reduce the load on the network or backend. For example, if your data changes every hour, then you don't need to set the dashboard refresh rate to 30 seconds.
- Use the left and right Y-axes when displaying time series with different units or ranges. 
+- Use the left and right Y-axes when displaying time series with different units or ranges.
 -  Add documentation to dashboards and panels.
   - To add documentation to a dashboard, add a [Text panel visualization]({{< relref "../panels/visualizations/text-panel.md" >}}) to the dashboard. Record things like the purpose of the dashboard, useful resource links, and any instructions users might need to interact with the dashboard. Check out this [Wikimedia example](https://grafana.wikimedia.org/d/000000066/resourceloader?orgId=1).
   - To add documentation to a panel, [edit the panel settings]({{< relref "../panels/add-a-panel.md#edit-panel-settings" >}}) and add a description. Any text you add will appear if you hover your cursor over the small `i` in the top left corner of the panel.
@@ -1,10 +1,6 @@
 +++
 title = "Best practices for managing dashboards"
 description = "Best practices for managing dashboards in Grafana"
-type = "docs"
-[menu.docs]
-identifier = "best-practices-for-managing-dashboards"
-parent = "best-practices"
 weight = 200
 +++

@@ -18,7 +14,7 @@ Here are some principles to consider before you start managing dashboards.

 ### Strategic observability

-There are several [common observability strategies]({{< relref "common-observability-strategies.md" >}}). You should research them and decide whether one of them works for you or if you want to come up with your own. Either way, have a plan, write it down, and stick to it. 
+There are several [common observability strategies]({{< relref "common-observability-strategies.md" >}}). You should research them and decide whether one of them works for you or if you want to come up with your own. Either way, have a plan, write it down, and stick to it.

 Adapt your strategy to changing needs as necessary.

@@ -3,10 +3,6 @@ title = "Common observability strategies"
 description = "Common observability strategies"
 keywords = ["grafana", "intro", "guide", "concepts", "methods"]
 aliases = ["/docs/grafana/latest/getting-started/strategies/"]
-type = "docs"
-[menu.docs]
-identifier = "common-observability-strategies"
-parent = "best-practices"
 weight = 300
 +++

@@ -19,7 +15,7 @@ A logical strategy allows you to make uniform dashboards and scale your observab
 ## Guidelines for usage

 - The USE method tells you how happy your machines are, the RED method tells you how happy your users are.
- USE reports on causes of issues. 
+- USE reports on causes of issues.
 - RED reports on user experience and is more likely to report symptoms of problems.
 - The best practice of alerting is to alert on symptoms rather than causes, so alerting should be done on RED dashboards.

@@ -1,10 +1,6 @@
 +++
 title = "Dashboard management maturity model"
 description = "Explanation of dashboard management maturity model"
-type = "docs"
-[menu.docs]
-identifier = "best-management-for-maturity-model"
-parent = "best-practices"
 weight = 400
 +++

@@ -35,8 +31,8 @@ At this stage, you are starting to manage your dashboard use with methodical das

 How can you tell you are here?

- Prevent sprawl by using template variables. For example, you don't need a separate dashboard for each node, you can use query variables. Even better, you can make the data source a template variable too, so you can reuse the same dashboard across different clusters and monitoring backends. 
-  
+- Prevent sprawl by using template variables. For example, you don't need a separate dashboard for each node, you can use query variables. Even better, you can make the data source a template variable too, so you can reuse the same dashboard across different clusters and monitoring backends.
+
  Refer to the list of [Variable examples]({{< relref "../variables/variable-examples.md" >}}) if you want some ideas.

 - Methodical dashboards according to an [observability strategy]({{< relref "common-observability-strategies.md" >}}).
@@ -49,7 +45,7 @@ How can you tell you are here?
  {{< imgbox max-width="100%" img="/img/docs/best-practices/service-hierarchy-example.png" caption="Example of a service hierarchy" >}}

 - Compare like to like: split service dashboards when the magnitude differs. Make sure aggregated metrics don't drown out important information.
- Expressive charts with meaningful use of color and normalizing axes where you can. 
+- Expressive charts with meaningful use of color and normalizing axes where you can.
  - Example of meaningful color: Blue means it's good, red means it's bad. [Thresholds]({{< relref "../panels/thresholds.md" >}}) can help with that.
  - Example of normalizing axes: When comparing CPU usage, measure by percentage rather than raw number, because machines can have a different number of cores. Normalizing CPU usage by the number of cores reduces cognitive load because the viewer can trust that at 100% all cores are being used, without having to know the number of CPUs.
 - Directed browsing cuts down on "guessing."