mirror of https://github.com/dapr/docs.git
				
				
				
			Updating guidance on providing diagrams in docs
Signed-off-by: msfussell <markfussell@gmail.com>
This commit is contained in:
		
							parent
							
								
									7aafdb2cba
								
							
						
					
					
						commit
						74c1efecaf
					
				|  | @ -19,7 +19,6 @@ Fork the [docs repository](https://github.com/dapr/docs) to work on any changes | |||
| Follow the instructions in the repository [README.md](https://github.com/dapr/docs/blob/master/README.md#environment-setup) to install Hugo locally and build the docs website. | ||||
| 
 | ||||
| ## Branch guidance | ||||
| 
 | ||||
| The Dapr docs handles branching differently than most code repositories. Instead of having a `master` or `main` branch, every branch is labeled to match the major and minor version of a runtime release. For the full list visit the [Docs repo](https://github.com/dapr/docs#branch-guidance) | ||||
| 
 | ||||
| Overall, all updates should go into the docs branch for the latest release of Dapr. You can find this directly at [https://github.com/dapr/docs](https://github.com/dapr/docs), as the latest release will be the default branch. For any docs changes that are applicable to a release candidate or a pre-release version of the docs, make your changes into that particular branch. | ||||
|  | @ -36,6 +35,14 @@ These conventions should be followed throughout all Dapr documentation to ensure | |||
| - **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. | ||||
| - **Use present tense** - Avoid sentences like "this command will install redis", which implies the action is in the future. Instead use "This command installs redis" which is in the present tense. | ||||
| 
 | ||||
| ## Diagrams and images | ||||
| It is strongly encouraged to create diagrams and images whereever possible for documentation pages. All diagrams are kept in a [diagram Powerpoint Deck](https://github.com/dapr/docs/tree/v1.6/daprdocs/static/images/dapr-diagrams.pptx) which has guidance on style and icons. The diagram images are saved as PNG files into the [images folder](https://github.com/dapr/docs/tree/v1.6/daprdocs/static/images).  | ||||
| Diagrams should be; | ||||
| - Saved as PNG files with a high resolution | ||||
| - Named using the convention of a concept or building block so that they are grouped. For example `service-invocation-overview.png`. Also see Images guidance section below. | ||||
| - Added to the correct section in the `Dapr-Diagrams.pptx` deck so that they can be amended and updated. | ||||
| 
 | ||||
| 
 | ||||
| ## Contributing a new docs page | ||||
| - Make sure the documentation you are writing is in the correct place in the hierarchy. | ||||
| - Avoid creating new sections where possible, there is a good chance a proper place in the docs hierarchy already exists. | ||||
|  | @ -50,7 +57,6 @@ These conventions should be followed throughout all Dapr documentation to ensure | |||
| - Where possible reference a practical How-To doc. | ||||
| 
 | ||||
| ### Contributing a new How-To guide | ||||
| 
 | ||||
| - `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. | ||||
| - 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. | ||||
|  |  | |||
										
											Binary file not shown.
										
									
								
							
		Loading…
	
		Reference in New Issue