mirror of
				https://github.com/zulip/zulip.git
				synced 2025-10-31 20:13:46 +00:00 
			
		
		
		
	docs: Expand help center guide for updating existing articles.
Adds a section on updating existing help center articles to the guide for writing help center documentation.
This commit is contained in:
		
				
					committed by
					
						 Tim Abbott
						Tim Abbott
					
				
			
			
				
	
			
			
			
						parent
						
							784f923dda
						
					
				
				
					commit
					8f7f486061
				
			| @@ -45,7 +45,7 @@ This system is designed to make writing and maintaining such documentation | |||||||
| highly efficient. We link to the docs extensively from the landing pages and | highly efficient. We link to the docs extensively from the landing pages and | ||||||
| in-product, so it's important to keep the docs up to date. | in-product, so it's important to keep the docs up to date. | ||||||
|  |  | ||||||
| ## Guide to writing documentation | ## Guide to writing help center articles | ||||||
|  |  | ||||||
| Writing documentation is a different form of writing than most people have | Writing documentation is a different form of writing than most people have | ||||||
| experience with. | experience with. | ||||||
| @@ -53,8 +53,8 @@ experience with. | |||||||
| ### Getting started | ### Getting started | ||||||
|  |  | ||||||
| There are over 100 feature articles and longer guides in the | There are over 100 feature articles and longer guides in the | ||||||
| [Zulip help center](https://zulip.com/help/), so use that as a resource | [Zulip help center](https://zulip.com/help/), so make the most of | ||||||
| and guide as you begin. | the current documentation as a resource and guide as you begin. | ||||||
|  |  | ||||||
| - Use the list on [Zulip help center home](https://zulip.com/help/) | - Use the list on [Zulip help center home](https://zulip.com/help/) | ||||||
|   to find the section of the docs (e.g. Display settings, Sending |   to find the section of the docs (e.g. Display settings, Sending | ||||||
| @@ -67,12 +67,15 @@ and guide as you begin. | |||||||
|   readability of the documentation. |   readability of the documentation. | ||||||
|  |  | ||||||
| - Should the feature you're documenting be added or merged into an | - Should the feature you're documenting be added or merged into an | ||||||
|   existing article? If so, you can locate that article in |   existing article? | ||||||
|   `templates/zerver/help` and start working on updating it with |  | ||||||
|   content about the new feature. |  | ||||||
|  |  | ||||||
| - If not, make a list of which articles (or guides) would be good to |   - If so, you can locate that article in | ||||||
|   link to as **Related articles** in your new feature documentation. |     `templates/zerver/help` and start working on updating it with | ||||||
|  |     content about the new feature. | ||||||
|  |  | ||||||
|  |   - If not, choose an existing article to use as a template for your | ||||||
|  |     new article and make a list of which articles (or guides) would be | ||||||
|  |     good to link to in your new feature documentation. | ||||||
|  |  | ||||||
| Remember that real estate in the left sidebar is somewhat precious. | Remember that real estate in the left sidebar is somewhat precious. | ||||||
| Minor features should rarely get their own article, and should instead | Minor features should rarely get their own article, and should instead | ||||||
| @@ -83,10 +86,39 @@ can always ask in | |||||||
| [#documentation](https://chat.zulip.org/#narrow/stream/19-documentation) | [#documentation](https://chat.zulip.org/#narrow/stream/19-documentation) | ||||||
| on the [Zulip community server](https://zulip.com/development-community/). | on the [Zulip community server](https://zulip.com/development-community/). | ||||||
|  |  | ||||||
|  | ### Updating an existing article | ||||||
|  |  | ||||||
|  | If the new feature you're documenting is a refinement on, | ||||||
|  | or related to, a feature that already has a dedicated help center | ||||||
|  | article, the information will be more useful and discoverable for | ||||||
|  | users as an addition to the existing article. | ||||||
|  |  | ||||||
|  | Here are some things to keep in mind when expanding and updating | ||||||
|  | existing help center articles: | ||||||
|  |  | ||||||
|  | - Maintain the format and style of the current article. | ||||||
|  |  | ||||||
|  | - Review the [Markdown features](#markdown-features) available and | ||||||
|  |   pay attention to the ones already utilized in the article. | ||||||
|  |  | ||||||
|  | - Think about where inline links to other help center documentation | ||||||
|  |   would be appropriate in the description of the feature. For example, | ||||||
|  |   your new feature might relate to general Zulip features like | ||||||
|  |   [keyboard shortcuts](https://zulip.com/help/keyboard-shortcuts) | ||||||
|  |   or [streams and topics](https://zulip.com/help/streams-and-topics). | ||||||
|  |  | ||||||
|  | - Make sure there is a **Related articles** section at the end | ||||||
|  |   of the article that again links to any help center documentation | ||||||
|  |   mentioned in the text or related to the feature. | ||||||
|  |  | ||||||
|  | Creating robust and informative help center articles with good links | ||||||
|  | will allow users to navigate the help center much more effectively. | ||||||
|  |  | ||||||
| ### Adding a new article | ### Adding a new article | ||||||
|  |  | ||||||
| If the feature you're documenting needs a new article, here are some | If the feature you're documenting needs a new article, here are some | ||||||
| things to keep in mind: | things to keep in mind, in addition to the points made above for | ||||||
|  | updating existing documentation: | ||||||
|  |  | ||||||
| - Choose an existing article in the related section of the help | - Choose an existing article in the related section of the help | ||||||
|   documentation, and copy the format, wording, style, etc. as closely |   documentation, and copy the format, wording, style, etc. as closely | ||||||
|   | |||||||
		Reference in New Issue
	
	Block a user