From dd5cad549cd08bfd4cb3cba5e2a89fa1496e4d76 Mon Sep 17 00:00:00 2001 From: Lauryn Menard Date: Mon, 1 Nov 2021 16:38:19 +0100 Subject: [PATCH] documentation: Expand documentation processes in new feature tutorial. Expands the developer tutorial 'Writing a new application feature' to include more detail about the documentation aspects of adding a new feature. Adds references to specific files that will be impacted and highlights API changes as well as writing `/help` articles. --- docs/documentation/overview.md | 2 +- docs/tutorials/new-feature-tutorial.md | 71 ++++++++++++++++++++------ 2 files changed, 57 insertions(+), 16 deletions(-) diff --git a/docs/documentation/overview.md b/docs/documentation/overview.md index c60a4453ab..bad55e1030 100644 --- a/docs/documentation/overview.md +++ b/docs/documentation/overview.md @@ -96,7 +96,7 @@ various extensions for macros and variable interpolation, (`render_markdown_path` in the code), designed to make it convenient to do the things one does a lot in each type of documentation. -### General user documentation +### End user documentation Zulip's [help center](https://zulip.com/help/) documentation is designed to explain how the product works to end users. We aim for diff --git a/docs/tutorials/new-feature-tutorial.md b/docs/tutorials/new-feature-tutorial.md index 9bfd621470..2940a907f2 100644 --- a/docs/tutorials/new-feature-tutorial.md +++ b/docs/tutorials/new-feature-tutorial.md @@ -64,6 +64,12 @@ organization in Zulip). The following files are involved in the process: admin settings pages. - `frontend_tests/node_tests/dispatch.js` +**Documentation** + +- `zerver/openapi/zulip.yaml`: OpenAPI definitions for the Zulip REST API. +- `templates/zerver/api/changelog.md`: documentation listing all changes to the Zulip Server API. +- `templates/zerver/help/...`: end user facing documentation (Help Center) for the application. + ### Adding a field to the database **Update the model:** The server accesses the underlying database in @@ -145,10 +151,22 @@ information on writing and running tests, see the ### Documentation changes -After implementing the new feature, you should -document it and update any existing documentation that might be -relevant to the new feature. For more information on the kinds of -documentation Zulip has, see [Documentation](../documentation/overview.md). +After implementing the new feature, you should document it and update +any existing documentation that might be relevant to the new feature. +For detailed information on the kinds of documentation Zulip has, see +[Documentation](../documentation/overview.md). + +**End user documentation:** You will likely need to at least update, +extend and link to `/help` articles that are related to your new +feature. See [User documentation](../documentation/user.md) for more +detailed information about writing and editing feature `/help` articles. + +**API documentation:** A new feature will probably impact the REST API +documentation as well, which will mean updating `zerver/openapi/zulip.yaml` +and modifying `templates/zerver/api/changelog.md` for a new feature +level. [Documenting REST API endpoints](../documentation/api.md) +explains Zulip's API documentation system and provides a step by step +guide to adding or updating documentation for an API endpoint. ## Example feature @@ -660,15 +678,38 @@ behavior of the setting you just created. ### Update documentation -After you add a new view, you should document your feature. This -feature adds new functionality that requires messages to have topics -if the setting is enabled. A recommended way to document this feature -would be to update and/or augment [Zulip's user -documentation](https://zulip.com/help/) to reflect your changes and -additions. +Nice job! You've added a new feature to Zulip that will improve user +and contributor experiences with the app, which is why it's really +important to make sure that your new feature is well documented. -At the very least, this will involve adding (or modifying) a Markdown file -documenting the feature to `templates/zerver/help/` in the main Zulip -server repository, where the source for Zulip's user documentation is -stored. For information on writing user documentation, see -[Zulip's general user guide documentation](../documentation/user.md). +This example feature adds new functionality that requires messages to +have topics if the setting is enabled. A recommended way to document +this feature would be to update and/or augment Zulip's existing +[end user documentation (Help Center)](https://zulip.com/help/) +to reflect your changes and additions. + +At the very least, this will involve modifying (or adding) a Markdown +file documenting the feature to `templates/zerver/help/` in the main +Zulip server repository, where the source for Zulip's end user +documentation is stored. Details about writing, editing and testing +these Markdown files can be found in: +[User documentation](../documentation/user.md). + +Also, new features will often impact Zulip's REST API documentation, +which is found in `zerver/openapi/zulip.yaml`. You may have noticed +this during the testing process as the Zulip test suite should fail if +there is a change to the API without a corresponding update to the +documentation. + +The best way to understand writing and updating Zulip's API +documentation is to read more about Zulip's +[REST API documentation process](../documentation/api.md) +and [OpenAPI configuration](../documentation/openapi.md). + +In particular, if there is an API change, **make sure** you document +your new feature in `templates/zerver/api/changelog.md` and bump the +`API_FEATURE_LEVEL` in `version.py`. The API feature level allows the +developers of mobile clients and other tools using the Zulip API to +programmatically determine whether the Zulip server they are +interacting with supports a given feature; see the +[Zulip release lifecycle](../overview/release-lifecycle.md).