mirror of https://github.com/dapr/docs.git
Adding guidance to How To article contribution
This commit is contained in:
Ori Zohar
parent
c699217a31
commit
e14d0d0d84
|
|
@ -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**
|
||||
- **\<Steps\>** times X as needed
|
||||
- **Cleanup**
|
||||
- **Related links**
|
||||
- Include code/sample/config snippets that can be easily copied and pasted.
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
>
|
||||
|
||||
|
||||
Loading…
Reference in New Issue