From e14d0d0d84df019bfda7cb229cb148a8a2d4afb5 Mon Sep 17 00:00:00 2001 From: Ori Zohar Date: Tue, 5 May 2020 20:09:14 -0700 Subject: [PATCH] Adding guidance to How To article contribution --- contributing/README.md | 17 +++++-- contributing/howto-template.md | 82 ++++++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+), 3 deletions(-) create mode 100644 contributing/howto-template.md diff --git a/contributing/README.md b/contributing/README.md index 53903f015..49f0f4133 100644 --- a/contributing/README.md +++ b/contributing/README.md @@ -5,6 +5,7 @@ High quality documentation is a core tenant of the Dapr project. Some contributi ## Style and tone - Use sentence-casing for headers. +- When referring to product names and technologies use capitalization (e.g. Kubernetes, Helm, Visual Studio Code, Azure Key Vault and of course Dapr). - Check the spelling and grammar in your articles. - Use a casual and friendly voice—like tone as if you're talking to another person one-on-one. - Use simple sentences. Easy-to-read sentences mean the reader can quickly use the guidance you share. @@ -13,7 +14,7 @@ High quality documentation is a core tenant of the Dapr project. Some contributi - Avoid the word “we”. We is generally not meaningful. We who? - Avoid the word “please”. This is not a letter asking for any help, this is technical documentation. - Assume a new developer audience. Some obvious steps can seem hard. E.g. Now set an environment variable DAPR to a value X. It is better to give the reader the explicit command to do this, rather than having them figure this out. -- Where possible give the reader links to next document/article for next steps. +- Where possible give the reader links to next document/article for next steps or related topics (this can be relevant "how-to", samples for reference or concepts). # Contributing to `Concepts` @@ -26,5 +27,15 @@ High quality documentation is a core tenant of the Dapr project. Some contributi # Contributing to `How-Tos` -- These should be practical. -- Include code/sample/config snippets that can be copy and pasted. +See [this template](./howto-template.md) for `How To` articles. + +- `How To` articles are meant to provide step-by-step practical guidance on to readers who wish to enable a feature, integrate a technology or use Dapr in a specific scenario. +- Location - `How To` articles should all be under the [howto](.\howto) directory in a relevant sub directories - make sure to see if the article you are contributed should be included in an existing sub directory. +- Sub directory naming - the directory name should be descriptive and if referring to specific component or concept should begin with the relevant name. Example *pubsub-namespaces* +- Do not assume the reader is using a specific environment unless the article itself is specific to an environment. This include OS (Windows/Linux/MacOS), deployment target (Kubernetes, IoT etc.) or programming language. If instructions vary between operating systems, provide guidance for all. +- How to articles should include the following sub sections: + - **Pre-requesties** + - **\** times X as needed + - **Cleanup** + - **Related links** +- Include code/sample/config snippets that can be easily copied and pasted. diff --git a/contributing/howto-template.md b/contributing/howto-template.md new file mode 100644 index 000000000..483c19c91 --- /dev/null +++ b/contributing/howto-template.md @@ -0,0 +1,82 @@ +# [Title] + +>Title should be descriptive of what this article helps achieve. Imagine it continues a sentence that starts with ***How to...*** so should start with a word such as "Setup", "Configure", "Implement" etc. +> +>Does not need to include the word *Dapr* in it (as it is in the context of the Dapr docs repo) +> +>If it is specific to an environment (e.g. Kubernetes), should call out the environment. +> +>Capital letters only for first word and product/technology names. +> +>Example: +># Set up Zipkin for distributed tracing in Kubernetes + +[Intro paragraph] + +> Intro paragraph should be a short description of what this article covers to set expectations of the reader. Include links if they can provide context and clarity to the reader. +> +> Example: +> +> This article will provide guidance on how to enable Dapr distributed tracing capabilities on Kubernetes using [Zipkin](https://zipkin.io/) as a tracing broker. + +## Pre-requisites + +>List the required setup this article assumes with links on how to achieve each prerequisite. +> +>Example: +> +> - [Setup Dapr on a Kubernetes cluster](https://github.com/dapr/docs/blob/master/getting-started/environment-setup.md#installing-dapr-on-a-kubernetes-cluster) +> - [Install Helm](https://helm.sh/docs/intro/install/) +> - [Install Python](https://www.python.org/downloads/) version >= 3.7 + +## [Step header] - (multiple) + +> +>Name each step section in a clear descriptive way which allows readers to understand what this section covers. Example: **Create a configuration file** +> +>If using terminal commands, make sure to allow easy copy/paste by having each terminal command in a separate line with the markdown (indented as needed when appearing in bullets or numbered lists). If Windows/Linux/MacOS instructions defer, make sure to include instructions for each. +> +>Example (note the indentation of the commands): +> +>- Clone the Dapr samples repository: +> ```bash +> git clone https://github.com/dapr/samples.git +> ``` +>- Go to the hello world sample: +> ``` +> cd 1.hello-world +> ``` +> +>Add sections as needed for multiple steps. +> + +## Cleanup + +> +> If possible, provide steps that undo the steps above. These should bring the user environment back to the pre-requisites stage. If using terminal commands, make sure to allow easy copy/paste by having each terminal command in a separate line with the markdown (indented as needed when appearing in bullets or numbered lists). If Windows/Linux/MacOS instructions defer, make sure to include instructions for each. +> +>Example: +> +>1. Delete the deployments from the cluster +> ``` +> kubectl delete -f file.yaml +> ``` +>2. Delete the Helm chart from the cluster +> ``` +> helm del --purge dapr-kafka +> ``` +> + +## Related links + +> +> Reference other documentation that may be relevant to a user interested in this How To. Include any of the following: +> +>- Other **How To** articles in related topics or alternative technology integrations. +>- **Concept** articles that are relevant. +>- **Reference** and **API** documentation that can be helpful +>- **Samples** that provide code reference relevant to this guidance. +>- Any other documentation link that may be a logical next step for a reader interested in this guidance (for example, if this is a how to on publishing to a pub/sub topic, a logical next step would be a how to which describes consuming from a topic). +> + +