diff --git a/contribute/templates/README.md b/contribute/templates/README.md new file mode 100644 index 00000000000..42dcc8ab72b --- /dev/null +++ b/contribute/templates/README.md @@ -0,0 +1,57 @@ +# Templates + +Templates are both a starting point and an instruction manual for writing something new. They are intended to make life easier by providing a jumping-off point, something besides a blank page to start from. They are not intended to be a limitation. If the template does not work perfectly for your use case, you can adjust or change it. We will work it out in code review. + +## Create a template + +Feel free to add templates to the `templates` folder. Try to make them as generic as possible and include clear instructions for when and how to use the template. Assume that the template user is a brand new contributor and write accordingly. + +## Use a template + +1. Read the template. Make sure you understand what it is for and how it is intended to be used. +1. Copy and rename the template. Move it to where you actually need it. + You might also want to copy the content of the template and paste it into a different file. This is acceptable use. +1. Replace the template content with your own. Delete whatever is unnecessary. + +## Documentation templates + +In an ideal world, each topic will correspond to an information *type* ([task](doc-task-template.md), [reference](doc-reference-template.md), [concept](doc-concept-template.md)) and contain only that type of information. + +However, this is not always practical. For example, you have a series of short topics, you can group them into one topic. + +Try to *chunk* your content. This means you should organize the document so that the same kinds of content are grouped together. + +### Chunking example + +If I was writing a topic called *Doggie handbook*, I might organize it like this. + +**Concept** +* What a dog is +* Brief history of dogs +* Why you might want a dog +* Tasks dogs can be trained to do + +**Tasks** +* Feed the dog +* Groom the dog +* Train the dog + +**Reference** +* List of dog equipment you will need +* Table of breeds that includes breed name, size range, short or long hair, and type of dog + +### Audience + +Write for an audience that is computer literate and has general technical knowledge, but is not necessarily familiar with Grafana or the finer points of observability. + +Pretend you are explaining your topic to a brand new Grafana user or developer. + +### Self-contained + +Thanks to search engines, every page in the documentation might be a reader's entry point. This means that each page needs to be self-contained and make sense on its own. The reader should not need to read other topics in order to perform the task or understand the concept. + +However, try to be helpful and link to related information. Using the *Doggie handbook* example, the concept topic that explains what dogs can be trained to do might link to the Train the dog task. + +## Code templates + +This is a placeholder for future templates. diff --git a/contribute/templates/doc-concept-template.md b/contribute/templates/doc-concept-template.md new file mode 100644 index 00000000000..effb9c99f0d --- /dev/null +++ b/contribute/templates/doc-concept-template.md @@ -0,0 +1,42 @@ +DELETE THIS LINE: If draft = false, then the document will not be built in the doc site. If the date is earlier than the build date, than the document will not show in the build site. Use these settings to control whether future content is shown in the doc site. ++++ +draft = "false" +date = "yyyy-mm-dd" +title = "Title in sentence case" +description = "Description in title case" +keywords = ["grafana", "enter", "keywords", "here"] +type = "docs" +[menu.docs] +name = "Name of topic" +identifier = "identifier" +parent = "menu parent" +weight = 100 ++++ + +# Concept + +The title of the concept topic will generally be a noun or a gerund. Examples include Templates, Templating, Dashboards, and panels. + +Concepts are topic types for any information that doesn't involve task lists or reference information. Ideally you use concept elements to explain concepts, ideas, overviews, workflows, and the like. In the intro section, this first paragraph or two, you should explain to the user what to expect in this topic or section. + +[Permissions overview](https://grafana.com/docs/grafana/latest/permissions/overview/) is an example of a concept topic. + +## Idea + +Concept topics or sections explain *what* and *why*. They do not explain *how*. If you are a new user, you might look for concept information to learn about what Grafana is, why it might be useful to you, and what the general workflow is. + +## Workflow + +Continuing the example in the previous section, here is a sample Grafana workflow. + +1. Install Grafana. +2. Set up data sources. +3. Create panels. +4. Create dashboards. +5. Enter queries. +6. Add users. +7. Create playlists. + +## Next steps + +Concept tasks often link to related information, including *tasks* related to the concept and *reference* topics related to the concept. diff --git a/contribute/templates/doc-reference-template.md b/contribute/templates/doc-reference-template.md new file mode 100644 index 00000000000..cd3bb73560a --- /dev/null +++ b/contribute/templates/doc-reference-template.md @@ -0,0 +1,75 @@ +DELETE THIS LINE: If draft = false, then the document will not be built in the doc site. If the date is earlier than the build date, than the document will not show in the build site. Use these settings to control whether future content is shown in the doc site. ++++ +draft = "false" +date = "yyyy-mm-dd" +title = "Title in sentence case" +description = "Description in title case" +keywords = ["grafana", "enter", "keywords", "here"] +type = "docs" +[menu.docs] +name = "Name of topic" +identifier = "identifier" +parent = "menu parent" +weight = 100 ++++ + +# Reference + +The *reference* topic type is for storing reference information, such as extensive tables, lists, or other information that is used as support for a task. Reference topics are also designed for API information. + +Often reference topics are linked from *task* topics, because they contain information the user needs in order to perform a task. + +[Grafana CLI](https://grafana.com/docs/grafana/latest/administration/cli/) is one example of a reference topic. + +## Lists + +Lists of commands or parameters are often organized in reference topics. The information you need to present will dictate the format. + +* They might +* be in +* unordered lists. + +[Configuration](https://grafana.com/docs/grafana/latest/installation/configuration/) is an example of lists. + +## Tables + +If you have a large list of things to store in a table, then you are probably dealing with reference information. Hugo accepts either tables in Markdown or in HTML format, so use whichever is easier for you. + +The [Glossary](https://grafana.com/docs/grafana/latest/guides/glossary/) provides an example of reference data in a table. + +### Empty markdown table + +While you might not need a heading for each table, headings are a good way to chunk information if you have several tables. They also make the content easy to skim. Use headings or intro paragraphs like this one to explain to the reader what the information in the table is used for. + +| | | | | | | +|:---|:---|:--:|:--:|---:|---:| +| | | | | | | +| | | | | | | +| | | | | | | +| | | | | | | + +### Empty HTML table + +And here is intro text, similar to the paragraph in the previous section. Do not add local styling to the table. The website CSS will take care of that for you. + + + + + + + + + + + + + + + + + +
FirstnameLastnameAge
JillSmith50
EveJackson94
+ +## API documentation + +API documentation is always a reference topic rather than a task topic, but it has its own rules. diff --git a/contribute/templates/doc-task-template.md b/contribute/templates/doc-task-template.md new file mode 100644 index 00000000000..f3217f5a8e7 --- /dev/null +++ b/contribute/templates/doc-task-template.md @@ -0,0 +1,57 @@ ++++ +draft = "false" +date = "yyyy-mm-dd" +title = "Title in sentence case" +description = "Description in title case" +keywords = ["grafana", "enter", "keywords", "here"] +type = "docs" +[menu.docs] +name = "Name of topic" +identifier = "identifier" +parent = "menu parent" +weight = 100 ++++ + +# Task + +A *task* topic is intended for a procedure that describes how to accomplish a task. It lists a series of steps that users follow to produce an intended outcome. It tells the reader *how* to do something. [Install Grafana plugins](https://grafana.com/docs/grafana/latest/plugins/installation/) and [Playlist](https://grafana.com/docs/grafana/latest/reference/playlist/) are examples of task topics. Playlist includes a small amount of concept information in the introduction, which is appropriate. + +Always include an introduction of a short paragraph or two to explain what the task is for, perhaps give the reader an idea of what the outcome will be. + +In most cases, each topic should only contain one task. If you have several very short, related tasks, then you might combine them into one topic. + +In the case of a long task, then you probably won't need any headings except for the h1 at the top of the page. + +1. Start with step one. +1. Use second-person imperative tense. +1. Basically, "You, do this" with every sentence. +1. Do not use the third-person "user" for steps you want the reader ("you") to perform. +1. Write steps that contain one action, possibly two related actions, such as copy and paste a thing or save and quite the program. + If a sentence is not telling the reader to do something, then it is not a step. You can use nested images or paragraphs like this one to add information if necessary. + +In many cases, you should tell the reader what the outcome should be so that they know when they are done. + +## One-step task + +Some tasks are so short, they only contain one step. + +Write one-step tasks as simple sentences, not as unordered lists or numbered lists. + +## Short task + +Short tasks can be grouped. How short constitutes "short" is a judgment call based on number of steps and how long individual steps are. + +1. Use your judgment. +2. Ask your coworkers or someone on the Comm team for advice if you aren't sure. + +## Next steps + +If the task you are writing leads naturally to one or more other tasks, then include links after the task to help the reader figure out where to go next. + +Thanks to internet search engines, every page in the documentation could be page one. Pretend you are explaining your task to a new Grafana user who just walked in off the street. + +## Testing + +It is a good practice to have someone else test the task you have written. If they can successfully complete the task using *only* what the steps you have written, not guessing or using their inherent knowledge, then your task has passed the test. However, it is very common to find you have skipped steps, because *you* are very familiar with Grafana and the topic you are explaining. + +New users or people from other teams are very helpful for these tests.