diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index dec79802f..93a3d8923 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,3 +1,31 @@ -# Main global owner # -##################### -* +# Each of these groups of CODEOWNERS have approval and merge authority over +# the noted directories. +# +# If you want to add, modify, or delete files in any of these directories, +# open a pull request. Then add the appropriate group name (without the `@`) +# to the list of "Reviewers." +# +# Order is important; the last matching pattern takes precedence. +# For example, when someone opens a pull request that only modifies files +# in the content/nginx-one directory, you should assign @nginxinc/one-docs-approvers +# as a reviewer. +# +# Lines starting with '#' are comments. +# Each line is a file pattern followed by one or more owners. + +# DocOps +* @nginxinc/nginx-docs +# NGINX Plus +content/nginx/* @nginxinc/plus-docs-approvers +# NGINX Agent +content/nginx/nms/agent/* @nginxinc/agent-docs-approvers +# NGINX One +content/nginx-one/* @nginxinc/one-docs-approvers +# NGINX Instance Manager +content/nms/nim/* @nginxinc/nim-docs-approvers +content/nim/* @nginxinc/nim-docs-approvers +# NGINX App Protect WAF +content/nap-waf/* @nginxinc/nap-docs-approvers +data/nap-waf/* @nginxinc/nap-docs-approvers +# NGINX App Protect DoS +content/nap-dos/* @nginxinc/dos-docs-approvers diff --git a/CHANGELOG.md b/CHANGELOG.md index da02d3637..8276954e6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,7 @@ # Changelog + + ## 1.0.0 (Month Date, Year) -Initial release of the NGINX template repository. +Initial open source release of the documentation repository for enterprise NGINX products. This is a filtered mirror of an internal repository. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c1faf9e5c..0734cdf1e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,57 +1,92 @@ -# Contributing Guidelines +# Contributing guidelines -The following is a set of guidelines for contributing to this project. We really appreciate that you are considering contributing! +The following is a set of guidelines for community contributions to this +project. We really appreciate your desire to contribute! -#### Table Of Contents +If you are an F5/NGINX employee, see the following guidance [For F5/NGINX Employees](./F5-NGINX-team-notes.md). -[Getting Started](#getting-started) +## Table of contents -[Contributing](#contributing) +- [Report a Bug](#report-a-bug) +- [Suggest a Feature or Enhancement](#suggest-a-feature-or-enhancement) +- [Open a Discussion](#open-a-discussion) +- [Submit a Pull Request](#submit-a-pull-request) + - Review our [Git style guide](#git-style-guide) + - Review our Documentation [style guide](./templates/style-guide.md) +- [Issue Lifecycle](#issue-lifecycle) +- [Content edited elsewhere](#content-edited-elsewhere) +- [F5 Contributor License Agreement (CLA)](#f5-contributor-license-agreement) -[Code Guidelines](#code-guidelines) +## Report a bug -[Code of Conduct](/CODE_OF_CONDUCT.md) +To report a bug, open an issue on GitHub with the label `bug` using the +available bug report issue template. Before reporting a bug, make sure the +issue has not already been reported. -## Getting Started +## Suggest a feature or enhancement -Follow the instructions on the README's [Getting Started](/README.md#Getting-Started) section to get this project up and running. +To suggest a feature or enhancement, open an issue on GitHub with the label +`feature` or `enhancement` using the available feature request issue template. +Please ensure the feature or enhancement has not already been suggested. - +## Open a discussion -## Contributing +If you want to start a conversation with the community and maintainers, +we encourage you to use +[GitHub Discussions](https://github.com/nginxinc/oss-docs/discussions). -### Report a Bug +## Submit a Pull Request -To report a bug, open an issue on GitHub with the label `bug` using the available bug report issue template. Please ensure the bug has not already been reported. **If the bug is a potential security vulnerability, please report it using our [security policy](/SECURITY.md).** +To contribute to F5 NGINX documentation, follow these steps: -### Suggest a Feature or Enhancement +- Fork the NGINX repository +- Create a branch +- Implement your changes in your branch +- Submit a pull request (PR) when your changes are ready for review -To suggest a feature or enhancement, please create an issue on GitHub with the label `enhancement` using the available [feature request template](/.github/feature_request_template.md). Please ensure the feature or enhancement has not already been suggested. +Alternatively, you're welcome to suggest improvements to highlight problems with +our documentation as described in our [support](./SUPPORT.md) page. -### Open a Pull Request (PR) +### Git Style Guide -- Fork the repo, create a branch, implement your changes, add any relevant tests, and submit a PR when your changes are **tested** and ready for review. -- Fill in the [PR template](/.github/pull_request_template.md). +- Keep a clean, concise and meaningful Git commit history on your branch, rebasing locally and squashing before you submit a PR +- Follow the guidelines of writing a good commit message as described here + and summarized in the next few points: -**Note:** If you'd like to implement a new feature, please consider creating a [feature request issue](/.github/feature_request_template.md) first to start a discussion about the feature. + - In the subject line, use the present tense ("Add feature" not "Added feature") + - In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to...") + - Limit the subject line to 72 characters or less + - Reference issues and pull requests liberally after the subject line + - Add more detailed description in the body of the git message (`git commit -a` to give you more space and time in + your text editor to write a good message instead of `git commit -am`) -#### F5 Contributor License Agreement (CLA) +### Documentation style guide -F5 requires all external contributors to agree to the terms of the F5 CLA (available [here](https://github.com/f5/.github/blob/main/CLA/cla-markdown.md)) before any of their changes can be incorporated into an F5 Open Source repository. +For detailed guidance, see our documentation [style guide](./templates/style-guide.md). -If you have not yet agreed to the F5 CLA terms and submit a PR to this repository, a bot will prompt you to view and agree to the F5 CLA. You will have to agree to the F5 CLA terms through a comment in the PR before any of your changes can be merged. Your agreement signature will be safely stored by F5 and no longer be required in future PRs. +## Issue lifecycle + +To ensure a balance between work carried out by the NGINX team while encouraging community involvement on this project, we use the following +issue lifecycle: + +- A new issue is created by a community member +- An owner on the NGINX team is assigned to the issue; this owner shepherds the issue through the subsequent stages in the issue lifecycle +- The owner assigns one or more [labels](https://github.com/nginxinc/oss-docs/issues/labels) to the issue +- The owner, in collaboration with the community member, determines what milestone to attach to an issue. They may be milestones correspond to product releases + +## Content edited elsewhere -## Code Guidelines +This repository does not include all documentation available at https://docs.nginx.com. Other relevant repositories include: - +- [NGINX Open Source](https://github.com/nginx/nginx) +- [NGINX Unit](https://github.com/nginx/unit) +- [NGINX Ingress Controller](https://github.com/nginxinc/kubernetes-ingress/) +- [NGINX Gateway Fabric](https://github.com/nginxinc/nginx-gateway-fabric) -### Git Guidelines +You can find documentation source code in the `docs` or `site` subdirectories. -- Keep a clean, concise and meaningful git commit history on your branch (within reason), rebasing locally and squashing before submitting a PR. -- If possible and/or relevant, use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format when writing a commit message, so that changelogs can be automatically generated. -- Follow the guidelines of writing a good commit message as described here and summarized in the next few points: - - In the subject line, use the present tense ("Add feature" not "Added feature"). - - In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to..."). - - Limit the subject line to 72 characters or less. - - Reference issues and pull requests liberally after the subject line. - - Add more detailed description in the body of the git message (`git commit -a` to give you more space and time in your text editor to write a good message instead of `git commit -am`). +## F5 Contributor License Agreement + +F5 requires all external contributors to agree to the terms of the F5 CLA (available [here](https://github.com/f5/.github/blob/main/CLA/cla-markdown.md)) before any of their changes can be incorporated into an F5 Open Source repository. + +If you have not yet agreed to the F5 CLA terms and submit a PR to this repository, a bot will prompt you to view and agree to the F5 CLA. You will have to agree to the F5 CLA terms through a comment in the PR before any of your changes can be merged. Your agreement signature will be safely stored by F5 and no longer be required in future PRs. diff --git a/CONTRIBUTING_DOCS.md b/CONTRIBUTING_DOCS.md new file mode 100644 index 000000000..bba4e8394 --- /dev/null +++ b/CONTRIBUTING_DOCS.md @@ -0,0 +1,49 @@ +# Contributing guidelines for experts + +If you want to contribute, know Git, and can work from the command line, this page can help you. As noted in the [README](./README.md), we create source content for our documentation in Markdown. + +Once you add and/or edit our Markdown source files, you can build the content locally as described on this page. +Before you [Submit a Pull Request](#submit-a-pull-request), we recommend that you first: + +- Set up our [Static site generator](#static-site-generator) +- If you want to add images, review how to [Include images](#include-images) +- Learn how to [Build documentation locally](#build-documentation-locally) + +## Static site generator + +You will need to install Hugo to build and preview docs in your local development environment. +Refer to the [Hugo installation instructions](https://gohugo.io/getting-started/installing/) for more information. + +**NOTE**: We are currently running [Hugo v0.134.2](https://github.com/gohugoio/hugo/releases/tag/v0.134.2) in production. + +## Include images + +When you set up an image, this is the standard format: + +{{< img src="path/to/images/file-name.png" alt="descriptive text for screenreaders" >}} + +You'll find images in the [static](../static) subdirectory, in a directory associated with the documentation. For example, if you've set up the `file-name.png` +image, you should copy that file to the `static/path/to/images` directory. + +## Build documentation locally + +To build and preview docs in your local development environment, you need to install Hugo. +Refer to the [Hugo installation instructions](https://gohugo.io/getting-started/installing/) for more information. + +## Submit a Pull Request + +Follow this plan to contribute a change to NGINX source code: + +- Fork the NGINX repository +- Create a branch +- Implement your changes in this branch +- Submit a pull request (PR) when your changes are tested and ready for review + +### Add new docs + +Consistent with the [Diataxis](https://diataxis.fr) framework, our documentation includes the following content types: + +- concept: Helps a customer learn about a specific feature or feature set. +- tutorial: Walks a customer through an example use case scenario; results in a functional PoC environment. +- reference: Describes an API, command line tool, config options, etc.; should be generated automatically from source code. +- openapi: Contains front-matter and shortcode for rendering an openapi.yaml spec. diff --git a/F5-NGINX-team-notes.md b/F5-NGINX-team-notes.md new file mode 100644 index 000000000..3f184a46f --- /dev/null +++ b/F5-NGINX-team-notes.md @@ -0,0 +1,14 @@ +# For F5/NGINX Employees + +This repository is a functional mirror. If you want to make a change to F5/NGINX +documentation, use the private source repository. + +We encourage you to work with community contributors. If you participate in +PRs, issues, discussions, and more, follow these guidelines: + +- Follow the [Code of Conduct](./CODE_OF_CONDUCT.md). +- Be helpful. We want to encourage people who contribute to continue. +- Avoid references and links to internal content. +- Do not include information about future releases, changes, or features, unless + specifically authorized. +- Do not include information that is proprietary to and/or private within F5/NGINX. \ No newline at end of file diff --git a/LICENSE b/LICENSE index d9a10c0d8..4ea99c213 100644 --- a/LICENSE +++ b/LICENSE @@ -1,176 +1,395 @@ - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS +Attribution 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution 4.0 International Public License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution 4.0 International Public License ("Public License"). To the +extent this Public License may be interpreted as a contract, You are +granted the Licensed Rights in consideration of Your acceptance of +these terms and conditions, and the Licensor grants You such rights in +consideration of benefits the Licensor receives from making the +Licensed Material available under these terms and conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + d. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + e. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + f. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + g. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + h. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + i. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + j. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + k. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + 4. If You Share Adapted Material You produce, the Adapter's + License You apply must not prevent recipients of the Adapted + Material from complying with this Public License. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material; and + + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. diff --git a/README.md b/README.md index 0dcc803cf..04c774bef 100644 --- a/README.md +++ b/README.md @@ -2,75 +2,40 @@ [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) [![Community Support](https://badgen.net/badge/support/community/cyan?icon=awesome)](https://github.com/nginxinc/template-repository/blob/main/SUPPORT.md) [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](https://github.com/nginxinc/template-repository/main/CODE_OF_CONDUCT.md) +![Commercial Support](https://badgen.net/badge/support/commercial/green?icon=awesome) -# NGINX Template Repository + -## What is included on this template? +# NGINX documentation -This template includes all the scaffolding you need to get started on an OSS repository that meets the required NGINX criteria: +If you want to contribute to F5 NGINX documentation, you've come to the right place. We've organized a series of README-type files to help you get started: -- [Apache License 2.0](/LICENSE) (required for all NGINX OSS projects). -- [`.gitignore`](/.gitignore) with some minimal sensible defaults. -- [Issue](/.github/ISSUE_TEMPLATE) and [PR](/.github//pull_request_template.md) templates. -- [Contributing](/CONTRIBUTING.md) guidelines. -- [Support](/SUPPORT.md) guidelines for either community and/or commercial support (uncomment the commercial block if necessary). -- [Security](/SECURITY.md) guidelines for reporting major vulnerabilities. -- [Code of Conduct](/CODE_OF_CONDUCT.md). -- [F5 CLA workflow](/.github/workflows/f5-cla.yml). For more details on the action please check the [F5 CLA signature datastore repository](https://github.com/f5/f5-cla-data). -- Open Source Security Foundation (OSSF) Scorecard [(implemented via a GitHub Action)](/.github/workflows/ossf_scorecard.yml) -- [README](/README.md) placeholder. How you structure the README is up to you (although the template provides placeholder sections), but you will need to include: - - A [repostatus](https://www.repostatus.org/) badge. - - An OSSF Scorecard badge. (Optional -- Some projects will by their nature have low scores. In such a case you might want to remove this badge!). - - A community and/or commercial support badge. Include the latter -- and replace the commented out badge/URL placeholder with the relevant support URL -- if this repository contains a commercially supported project. You can find a commented out example below the community badge in this README. - - A contributor covenant/code of conduct badge. (Optional -- If you already have multiple badges and want to reduce clutter, simply including the actual code of conduct is enough!) - - An explicit link back to the [Apache License 2.0](/LICENSE). - - An up to date copyright notice. -- [Changelog](/CHANGELOG.md) placeholder. (Optional -- A changelog is recommended, but it is not required and can diverge in format from the placeholder here included.) -- [Codeowners](/.github/CODEOWNERS) placeholder. (Optional -- Codeowners is a useful feature, but not all repositories require them.) +- [Contributing](/CONTRIBUTING.md) describes how you can contribute to our documentation. + - [Contributing guidelines for experts](/CONTRIBUTING_DOCS.md) describes how you can contribute (and check your work) with Hugo, our static site generator +- [Code of Conduct](/CODE_OF_CONDUCT.md) describes expectations in the NGINX open source community. +- [License](/LICENSE) shows the license associated with work on this repository. +- [Security](/SECURITY.md) describes the procedures we would like you to follow if you find a security issue. +- [Support](/SUPPORT.md) lists how you can get support as a customer or a community member. -**Note:** If you created a public repository before this template became available (or you didn't know about it's existence), please include any missing files found here in your repository. There is no need if you have a private repository, but we still recommend you include all of the above scaffolding should the repository ever become public. +## Explanation -## How do I use this template? +This repository contains user documentation for NGINX's products, as well as the requirements for linting, building, and publishing the documentation. -**DO NOT FORK** -- this template is meant to be used from the **[`Use this template`](https://github.com/nginxinc/template-repository/generate)** feature. +Our documentation is written in Markdown, specifically the [Goldmark](https://github.com/yuin/goldmark) Markdown parser. +We build our docs using [Hugo](https://gohugo.io) and host them in custom URLs on Azure. -1. Click on **[`Use this template`](https://github.com/nginxinc/template-repository/generate)**. -2. Give a name to your project. -3. Wait until the first run of CI finishes (GitHub Actions will process the template and commit to your new repo). -4. Clone your new project and tweak any of the placeholders if necessary. Pay special attention to the README! -5. Happy coding! +## Publishing environments -**NOTE**: **WAIT** until the first CI run on GitHub Actions finishes before cloning your new project. +When you submit a Pull Request (PR), our setup automatically builds the documentation with your proposed changes. You'll see the URL +once you've submitted the PR. ---- - - - -[![Project Status: Concept – Minimal or no implementation has been done yet, or the repository is only intended to be a limited example, demo, or proof-of-concept.](https://www.repostatus.org/badges/latest/concept.svg)](https://www.repostatus.org/#concept) -[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/nginxinc/oss-docs/badge)](https://securityscorecards.dev/viewer/?uri=github.com/nginxinc/oss-docs) -[![Community Support](https://badgen.net/badge/support/community/cyan?icon=awesome)](/SUPPORT.md) -[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](/CODE_OF_CONDUCT.md) - -# oss_docs - -## Requirements - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam elit turpis, varius et arcu elementum, viverra rhoncus sem. Aliquam nec sodales magna, et egestas enim. Mauris lobortis ultrices euismod. Pellentesque in arcu lacus. Mauris cursus laoreet nulla, ac vehicula est. Vestibulum eu mauris quis lorem consectetur aliquam ac nec quam. Vestibulum commodo pharetra mi, at bibendum neque faucibus ut. Mauris et tortor sed sem consectetur eleifend ut non magna. Praesent feugiat placerat nibh, varius viverra orci bibendum sed. Vestibulum dapibus ex ut pulvinar facilisis. Quisque sodales enim et augue tempor mattis. Suspendisse finibus congue felis, ac blandit ligula. Praesent condimentum ultrices odio quis semper. Nunc ultrices, nibh quis mattis pellentesque, elit nulla bibendum felis, quis dapibus erat turpis ac urna. - -## Getting Started - -Duis sit amet sapien vel velit ornare vulputate. Nulla rutrum euismod risus ac efficitur. Curabitur in sagittis elit, a semper leo. Suspendisse malesuada aliquam velit, eu suscipit lorem vehicula at. Proin turpis lacus, semper in placerat in, accumsan non ipsum. Cras euismod, elit eget pretium laoreet, tortor nulla finibus tortor, nec hendrerit elit turpis ut eros. Quisque congue nisi id mauris molestie, eu condimentum dolor rutrum. Nullam eleifend elit ac lobortis tristique. Pellentesque nec tellus non mauris aliquet commodo a eu elit. Ut at feugiat metus, at tristique mauris. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia curae; - -## How to Use - -Maecenas at vehicula justo. Suspendisse posuere elementum elit vel posuere. Etiam quis pulvinar massa. Integer tempor semper risus, vitae maximus eros ullamcorper vitae. In egestas, ex vitae gravida sodales, ipsum dolor varius est, et cursus lorem dui a mi. Morbi faucibus ut nisi id faucibus. Sed quis ullamcorper ex. In et dolor id nunc interdum suscipit. +## License -## Contributing +[Creative Commons License](/LICENSE) -Please see the [contributing guide](/CONTRIBUTING.md) for guidelines on how to best contribute to this project. +© [F5, Inc.](https://www.f5.com/) 2024 -## License -[Apache License, Version 2.0](/LICENSE) +## Credits -© [F5, Inc.](https://www.f5.com/) 2024 +- [The Good Docs Project](https://www.thegooddocsproject.dev/), whose templates we've adapted for our use. diff --git a/SUPPORT.md b/SUPPORT.md index 1cedd288d..8d67c82d1 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -6,17 +6,15 @@ We use GitHub for tracking bugs and feature requests related to this project. Don't know how something in this project works? Curious if this project can achieve your desired functionality? Please open an issue on GitHub with the label `question`. +Alternatively, open a [discussion](https://github.com/nginxinc/oss-docs/discussions) in this repository. + ## NGINX Specific Questions and/or Issues This isn't the right place to get support for NGINX specific questions, but the following resources are available below. Thanks for your understanding! -### Community Slack - -We have a community [Slack](https://nginxcommunity.slack.com/)! - -If you are not a member, click [here](https://community.nginx.org/joinslack) to sign up. (Let us know if the link does not seem to be working at !) +### Mailing List -Once you join, check out the `#beginner-questions` and `nginx-users` channels :) +Want to get in touch with the NGINX development team directly? Try using the relevant mailing list found at ! ### Documentation @@ -24,18 +22,14 @@ For a comprehensive list of all NGINX directives, check out . For a comprehensive list of administration and deployment guides for all NGINX products, check out . -### Mailing List - -Want to get in touch with the NGINX development team directly? Try using the relevant mailing list found at ! - ## Contributing Please see the [contributing guide](/CONTRIBUTING.md) for guidelines on how to best contribute to this project. - +Commercial support for these projects may be available. Please get in touch with [F5 NGINX sales](https://www.f5.com/products/get-f5) or check your contract details for more information. ## Community Support -This project does **not** offer commercial support. Community support is offered on a best effort basis through either GitHub issues/PRs/discussions or via any of our active communities. +We offer community support on a best effort basis through either GitHub issues/PRs/discussions or through our active communities. diff --git a/templates/concept/coffee-img.jpg b/templates/concept/coffee-img.jpg new file mode 100644 index 000000000..1b7f6d85b Binary files /dev/null and b/templates/concept/coffee-img.jpg differ diff --git a/templates/concept/example-concept.md b/templates/concept/example-concept.md new file mode 100644 index 000000000..f263aad27 --- /dev/null +++ b/templates/concept/example-concept.md @@ -0,0 +1,72 @@ +# Coffee + +This document is a guide to the fundamental concepts of making and drinking coffee. + +Coffee is a popular beverage prepared from roasted coffee beans, the seeds of berries from certain coffee species. It is known for its stimulating effect due to its caffeine content, and is consumed globally in various forms like espresso, cappuccino, latte, and more. + +By drinking coffee, you can enjoy a variety of benefits such as increased alertness, improved mood, and enhanced cognitive function. + +![An image of a glass mug containing coffee with steam rising from it, next to a bag of coffee beans and a french press](coffee-img.jpg) + + +## Background + +The history of coffee dates back to the 15th century, and possibly earlier with a number of reports and legends surrounding its first use. The native origin of coffee is thought to have been Ethiopia, with several mythical accounts but no solid evidence. The earliest substantiated evidence of either coffee drinking or knowledge of the coffee tree is from the early 15th century, in the Sufi monasteries of Yemen, spreading soon to Mecca and Cairo. + +Nbeamex Coffee is sourced from an organic farm in an undisclosed location. Secrecy is necessary to protect the proprietary sustainable harvesting and roasting methods that make Nbeamex Coffee so rich and flavorful. + +## Use cases + +There are many different ways to brew Nbeamex coffee. In this section, you will learn about some popular methods of making coffee and the benefits each provides. + +### French Press + +Method: Coarsely ground coffee is steeped in hot water for a few minutes, then pressed to separate the grounds from the liquid. + +Reasons to use: + +- Produces a full-bodied and rich flavor. +- Allows for more control over the brewing process. +- Easy to use and requires minimal equipment. + +### Espresso + +Method: Highly pressurized hot water is forced through finely ground coffee, resulting in a concentrated and flavorful shot. + +Reasons to use: + +- Produces a strong and intense flavor. +- Allows for the creation of various coffee-based drinks like lattes and cappuccinos. +- Brews quickly, making it ideal for those who need a quick caffeine fix. + +### Pour Over + +Method: Hot water is poured over a filter containing medium-fine ground coffee, allowing it to slowly drip into a container. + +Reasons to use: + +- Produces a clean and bright flavor profile. +- Offers precise control over the brewing process. +- Showcases the unique characteristics of different coffee beans. + +## Conclusion + +This document provides an overview of coffee's history and presents a few popular methods you can use to get the most of your Nbeamex Coffee, including French press, espresso, and pour over. The methods described here are just a few examples of the ways you can make coffee. Other methods include Aeropress, Moka pot, and cold brew. Each method has its own unique characteristics and can result in different flavors and brewing experiences. + +Experimenting with different brewing methods can be a fun way to explore the world of Nbeamex Coffee. + +## Additional Resources + +How-to guides + +- [Grind Coffee](../how-to/grind-coffee.md) + +Tutorials + +- [How to Make Coffee](../tutorial/example-tutorial.md) + +Release Notes + +- [Nbeamx Coffee Releases](../release-notes/example-release-notes.md) + +--- \ No newline at end of file diff --git a/templates/concept/guide-concept.md b/templates/concept/guide-concept.md new file mode 100644 index 000000000..4602550f1 --- /dev/null +++ b/templates/concept/guide-concept.md @@ -0,0 +1,406 @@ +# Concept template guide + + +> Thank you for downloading this template from The Good Docs Project! Before using the template, read this template guide for information about how to complete each section. Want to explore more templates? Check them out in our [templates GitLab repository](https://gitlab.com/tgdp/templates). + +## What is a concept doc? + +A concept document serves as a comprehensive guide, offering clear, concise, and consistent information +on a specific concept or process. +It acts as a roadmap, logically organizing information to enhance comprehension and readability. +By providing essential background information, it enables readers to align their existing knowledge +with the tasks they need to perform and gain valuable insights into products, processes, or systems. + +For instance, a concept document called "Object-oriented programming" +would offer a structured explanation of the core principles of OOP, +helping team members gain a deeper understanding of this programming +paradigm and serving as a bridge towards implementing OOP effectively in +software development projects and facilitating the application of these +principles in practice. + +Concept documents can be thought of as extended definitions of major +abstractions, such as a mechanism or a function. They help explain the +context and components of a product or service and how these elements +fit into a broader framework. + +## Why do I need a concept doc? + +A concept document is important for conveying foundational ideas or +processes. The key reasons why a concept document is integral include +the following: + +- **Alignment and collaboration**: A concept document serves as a shared point of reference for businesses and teams, holding high-level ideas and enabling all stakeholders to align their understanding and expectations. +By having a shared document that holds the ideas, it is much easier to communicate ideas and track progress. Having a central +description of core concepts reduces repeated explanations through a document. It is much easier to have a concept document that can then be referenced when needed. + +- **Reader comprehension**: Concept documents are important because they provide foundational knowledge and background that gives readers context that will help in understanding more specific content. +Readers can see the connections and relationships between different elements, helping them make informed decisions about your product. Decision-making is much easier to do if the reader understands the broader context. + +A concept doc presents information at the appropriate level of detail to help readers: + +- Proceed to other types of content, such + as how-tos and reference, with all the foundational knowledge, + background and context necessary to use the tool or system. + +- Make an informed decision about using certain + features of your solution and prioritize efforts throughout the + development process. + +- Know how certain concepts relate to the broader + context. They can see the connections and relationships between + different elements and how they fit into a bigger picture. + +## Where is its place in the whole documentation? + +A concept document provides the necessary context and foundational +understanding for new ideas, processes or features that are introduced. + +They act as a bridge between the overall ideas and the more detailed +instructions or guides, allowing readers to understand the core of what +is going on before they move on to more complex operations. It also acts +as a primer for users who are not yet ready to dive into concrete +operations or step-by-step guides. By presenting the core concepts and principles in a +clear and structured manner, the concept doc gradually develops the +reader's understanding. + +## How does the reader get to this document? + +In the reader's critical user journey through documentation, a concept +document is usually in the early sections. While concept documents are +commonly found at the beginning of documentation, they can also appear +throughout when introducing new concepts to provide the necessary +context. + +There are two main options here: + +1. Users start their journey with this document or land here from the search results. + +2. Users get there in the middle of their journey because they stumbled upon an unknown concept. +In this case, the document serves as a middle layer (to make a decision about using this concept). + +Ryan Young in the talk "Is it (layer) cake: Thinking in content levels" calls this +approach a layered cake (of content). Users use mid-level documentation to close the gaps between low (execution) and high (overview) level. +You will use them to help users decide what to do next. Therefore, you can present integration guides, use cases, and broad concepts on this level. + +It is important to notice that users will not follow a defined flow through the documentation. +They may jump through different levels of content as they need to. + +They may land in your concept document by clicking a link in the How-to document prerequisites +or by clicking a link from a related concept document. + +Understanding these pathways is essential for tailoring the content to +meet the varying needs of users who either start their exploration with +the concept or arrive here as part of an ongoing information quest. + +## Contents of the concept document + +Sections which should exist in a concept template include: + +### (Optional) An introductory paragraph + +Optionally, you may begin the document with an introductory paragraph +before diving into the definition. This introductory paragraph can set +the stage, explaining the concept's relevance and importance. It +provides readers with a context for what they're about to learn and +what they can expect in the document. + +Apply the inverted pyramid technique here by starting with a high-level overview. + +You may skip it and jump right into the definition section. + +### Giving a definition + +Define the concept so that you and your reader will have a shared +understanding of the language used throughout the document.Think of it +as a glossary definition. + +This is a good moment to define the scope of the concept – define its +boundaries, what you'll cover in a document and how deep into details +you will dive and the extent of the details you will provide. + +It may be useful to define what is out of scope – what you don't mean +by that concept and what won't be covered. If the concept has synonyms +in other spheres or products, it may be useful to explicitly +disassociate from them in this section of the document to ensure a +uniform understanding of the concept. + +Provide an overview of how the concept fits into a bigger picture. This +involves explaining how the concept interacts with other concepts +[already known by your +audience](#use-known-concepts-and-examples), provided you +have knowledge of their level of understanding. Additionally, you can +break down the concept into smaller, more digestible pieces. By doing +so, you help your readers make connections, recognize patterns, and gain +a deeper understanding of the subject matter. + +Sometimes, concepts are explained by using +[analogies](#metaphors-and-analogies) that the user should +be familiar with. For example, while explaining the complex topic of how +electricity goes through wires, you could relate it to a more familiar +topic, such as how water goes through pipes. It helps to bridge +knowledge gaps. + +Also, when you give a definition, it may be useful to stick to +problem-solution or benefit-focused language. + +### (Optional) A visual aid or a diagram + +Use a diagram to illustrate how the concept is organized or how it fits +into a broader system; a decision tree, a flow chart, or a system +overview diagram is best suited for these tasks. + +Usually a concept is best explained with one diagram. This primary +diagram should be placed close to the top, typically under the +description. Presenting the diagram early helps draw the reader in, and +helps them orient themselves visually. + +Sometimes multiple diagrams should be used to explain different aspects +of the concept, and these should be placed next to relevant annotations +about it. + +To enhance the clarity of a diagram illustrating a process related to the concept, +consider adding numbered elements within the diagram itself. +Additionally, including a legend positioned at the bottom of the picture can explain +the meaning behind each numbered component. + +Diagrams are most valuable when they simplify complex relationships, +depict processes, or illustrate hierarchies. Be cautious not to overwhelm the document with unnecessary visuals +if the concept is easily explained through text alone. + +### (Optional) About the "Background" section + +The background section may describe the prehistory of the concept if it +is important for better understanding. You can provide relevant +information and context that helps readers understand the following +contexts: + +- Historical background (where the idea originated from, is there any + legacy that made it work like that). + +- Industry context (any significant changes in the sector you're + working in that influenced the concept). + +- Market and technology trends, any new disruptive technologies that + appear (Artificial Intelligence(AI)), business trends (recession, remote work), or industry + regulations (for instance, General Data Protection Regulation (EU GDPR)). + +It can describe how or why something was designed or developed, what +decisions were made in the past and why. In addition, you can describe +the alternatives. + +### About the "Use cases" section + +The use cases section is a good place to apply the StoryBrand framework (referred in the [Resources document](resources-concept.md)) +to engage readers and add more storytelling elements. Storytelling helps +engage users and memorize concepts by association with the story. +Research in neuroscience has revealed that narratives, such as those +applied in the StoryBrand framework, engage multiple areas of the brain +and the distinction between reading and real-life gets blurred. +Read more regarding that in the [Resources document](resources-concept.md). + +The Storybrand technique is a specific approach to storytelling that +involves framing the story in terms of a protagonist who has a problem +and needs a guide to help them solve it. The concept or solution being +presented is positioned as the guide that can help the protagonist +overcome their challenges and achieve their goals. By framing the +concept in this way, the reader is more likely to engage with the story +and see the product as a valuable solution to their problems. + +1. Make your user a protagonist of the story. + +2. Define what challenges they're facing, so you can craft a story that + resonates with them. + +3. Set the stage for the story. Highlight the specific problem or + obstacle that your target audience is encountering. Make it + relatable and evoke empathy. + +4. Position your concept or feature as the guide that can help the + protagonist overcome their challenges and achieve their goals. + Outline the steps or key concepts that the user needs to understand + to effectively use the product or feature. + +5. Illustrate how the user's life or business can be transformed by + using a concept. + +For example, you're talking about the containerisation concept, and your +"protagonist" is a system administrator in a large company, and they are +experiencing numerous typical problems, such as slow deployments, +difficulty scaling up service, or frequent power outages. So you act as +a guide and introduce the "protagonist" to containerised applications, +their infrastructure and how various aspects of these solve the +protagonist's problems. + +By following this framework, you can create a concept document that +captures attention, communicates the value of your product or feature, +and motivates readers to take action. + +When using storytelling as a technique in a concept document, it's +essential to strike a delicate balance between engaging the reader and +ensuring that the concept remains relevant and comprehensible. A common +pitfall for writers is becoming overly enthusiastic about their story, +which can lead to an overload of information that might distract from +the core concept. Thus, as you weave a story into your concept, always +consider how it enhances understanding rather than overwhelming your +audience with unnecessary details. + +### (Optional) About the "Comparison" section + +If the concept has few implementations, versions, or types, or it has a +direct preeceder, you may put in a comparison table. This table helps answer questions such as: +- What is the difference between this element and a similar element? +- Why do I need to choose a certain option? + +| What | Why needed | +|-----------------------|--------------------| +| {concept} type 1 | A reason to use it | +| {concept} type 2 | A reason to use it | + +### (Optional) About the "Related resources" section + +Provide links or references to additional resources that can help +readers explore the topic further or dive deeper into specific aspects +of the concept. + +If you have many related links, split them into a few groups (for example, How-to's, +Linked concepts, External materials, etc.), not more than 3-5 links +each, to avoid overwhelming a reader with a wall of links. + +## Best practices for concept documents + +Within the realm of concept documents, +there exist dozens of valid approaches and documentation techniques. +Each author, armed with their experience, must choose the right +technique tailored to the specific demands of the task at hand. + +Concept documents are more than just collections of ideas; they're a careful mix of clarity and detail. +Crafting them requires skill in both technical and narrative aspects, making it a significant challenge. +Choosing the right technique involves navigating communication intricacies to ensure that the document resonates with +its audience, serving as a beacon of understanding in the vast amount of +information. + +Here are the key practices for crafting an effective +concept document: + +### Scope + +The scope of your concept document is a foundational element. It should +be dedicated to a single concept and strike a balance between +comprehensiveness and relevance. Here\'s how to define the scope: + +- **Dedicate to a single concept**: Ensure that your document focuses on + just one concept to prevent confusion or information overload. If + the explanation begins to explain another concept, it is advisable + to start a different concept document and provide a link. + +- **Avoid instructional and referential information**: The concept + document should also avoid instructional text and step-by-step + guides which are different types of documentation. + +- **Select the right depth of understanding**: Dive deep enough to provide a thorough + understanding without overwhelming the reader. + +- **Define essential information**: Consider what would be valuable to + someone who has never encountered the concept before. Use this + perspective to define the scope. + +### Structure + +A well-structured concept document is crucial for enabling readers to +incrementally build their understanding of the concept. + +Consider the following practices: + +- **Inverted pyramid technique**: Consider using the inverted pyramid + technique, where you start with a high-level overview and then + gradually delve into the details. This approach helps readers + quickly grasp the main idea and then explore further as needed. + +- **Definition**: Provide a clear and concise definition of the concept. + +- **Key questions**: Address the key questions of what, when, who, why, + where, and how (5W and 1H), placing these explanations near the + beginning of your document. One more technique is to answer the question "How can I use it" or "How it helps me" from the + reader's perspective. + +- **Headings and subheadings**: Organize your ideas using headings and + subheadings to enhance readability and accessibility. + +- **Chunking**: Break down complex concepts into smaller parts, and use + abstraction to focus on the most important information. + +- **Real-world examples**: Include real-world examples and use cases to + provide context and help readers understand how the concept is + applied. + +### Language + +The language used in your concept document should prioritize clarity and +simplicity, tailored to the audience's expertise level. To enhance +accessibility: + +- **Minimize jargon**: Strive to minimize the use of domain-specific + jargon and technical terms to make the document more accessible, + especially for new users. + +- **Conversational tone**: Maintain a conversational tone that fully + engages the reader. + +- **Avoid implementation details**: Stay clear of delving into + implementation-specific details, as your document should focus on + the conceptual content. + +### Metaphors and analogies + +Metaphors and analogies are effective tools for enhancing the +relatability and clarity of your concept document. When using them: + +- **When to use metaphors and analogies**: Use them when they enhance + understanding, align with your audience's background, and bring + clarity and context. + +- **When to be cautious**: Exercise caution when there\'s a potential lack + of understanding due to cultural, age, or background differences or + when they might complicate the concept. + +A List Apart style guide (referred in the [Resources document](resources-concept.md#)) advises avoiding extended metaphors if +possible, so think case by case whether your audience will understand +them and if it adds anything to their understanding. + +Best practices for metaphors and analogies: + +- **Opt for universal metaphors**: Choose universal metaphors that are + culture, age, and background-independent. + +- **Ensure alignment**: Ensure that the metaphor or analogy seamlessly + aligns with the concept and enhances clarity. + +- **Understand your audience**: Consider your audience\'s familiarity with + the chosen metaphor before incorporating it into your document. + +While universal metaphors are generally safe and reliable, they may not +always be as engaging or memorable as more specific or popular culture +references. The decision to use universal metaphors or pop-culture +references should be guided by your understanding of your target +audience, concept complexity, and the specific goals of your concept +document. + +Analogies act as memory aids, turning abstract ideas into tangible +mental images. These mental images can serve as reference points when +your audience needs to recall the concept or explain it to others. + +### Use known concepts and examples + +Connect complex ideas with familiar concepts or examples to enhance +understanding: + +- **Pick familiar comparisons**: Choose comparisons and examples that are + easy to understand, considering your audience's background. + +- **Enhance understanding**: Linking new information to known concepts + helps readers grasp the new information more effectively. + + +--- + +> Explore other templates from [The Good Docs Project](https://thegooddocsproject.dev/). Use our [feedback form](https://thegooddocsproject.dev/feedback/?template=Concept%20guide) to give feedback on this template. \ No newline at end of file diff --git a/templates/concept/template-concept.md b/templates/concept/template-concept.md new file mode 100644 index 000000000..5af64b371 --- /dev/null +++ b/templates/concept/template-concept.md @@ -0,0 +1,108 @@ +# Concept template + +> If you need more information about how to fill in this template, read the accompanying [guide](./guide-concept.md). + +> This template includes writing instructions and boilerplate text that you can customize, use as-is, or completely replace with your own text. This text is indicated in {curly brackets}. Make sure you replace the placeholders with your own text. + +A summary paragraph introducing a concept, explaining its importance or +relevance, and providing an overview of the content that will be covered +in the document (scope). + +Typical wording to use is: +- This article explains the basics of {concept} and how it works in {the tool or context}. + +{Then include a paragraph with a definition of the concept you are explaining. +If more definitions are needed, include those definitions here as a bulleted list.} + +{This section usually doesn't have a separate heading that explicitly says +Definition; it can precede all the rest.} + +Typical wordings to use are: + +- {X} is; + +- {X} represents + +- {X} is connected to + +- {X} are organized {describe the way how} + +- {X} is similar to + +- {X} addresses the common pain points of ... + +- {X} solves the challenge of ... + +- By implementing {X}, users can ... + +- By using {X}, {specify users/target audience} gain ... + +- To use {X}, you create {Y} + +{Add visual aid to complement your explanations visually.} + +{Image goes here.} + +(Optional) Image/Figure: {Image title, which concisely explains the image or +figure. It can be represented by annotations on the image.} + +## (Optional) Background + +{Use this section to provide a reader with a context, prehistory, or background information.} + +Typical wordings to use are: + +- The reason {X} is designed that way is because historically, ... + +- The idea of {X} originated from the growing demand for ... + +- Recent advancements in {X} and {Y} have opened up new possibilities + for ... + +- With the rise of {X}, the need for things such as {Y} has become + paramount. + +- Over the past decade, {advancements in technology} have transformed + the way ... + +## Use cases + +{Use this section to provide use cases and explain how a reader can +benefit from a concept.} + +## (Optional) Comparison of {thing being compared} + +{Use this section to compare options or alternatives.} + +Table: {Table title which concisely explains the comparison.} + +## (Optional) Related resources + +{Use this section to provide links to documentation related to the concept that the user can read for more information. +If you can name this section manually (it is not generated automatically or has a heading pre-agreed within a team), +we recommend to use "Related concepts" or "Additional information" as more descriptive ones.} + +If you would like to dive deeper or start implementing {concept}, +check out the following resources: + +How-to guides + +1. Item 1 + +2. Item 2 + +Linked concepts + +1. Concept 1 + +2. Concept 2 + +External resources + +1. Resource 1 + +2. Resource 2 + +--- + +> Explore other templates from [The Good Docs Project](https://thegooddocsproject.dev/). Use our [feedback form](https://thegooddocsproject.dev/feedback/?template=Concept) to give feedback on this template. \ No newline at end of file diff --git a/templates/getting-started/example-getting-started.md b/templates/getting-started/example-getting-started.md new file mode 100644 index 000000000..a5572de24 --- /dev/null +++ b/templates/getting-started/example-getting-started.md @@ -0,0 +1,56 @@ +# Getting Started with Your New Coffee Maker + +## Introduction + +Welcome to the world of brewing delicious coffee at home! This guide will walk you through the basics of setting up your coffee maker, grinding coffee beans, and brewing a standard cup of coffee. Your new coffee maker is designed to efficiently brew coffee to your desired flavor and strength. Let’s get started! + +## Before You Begin + +Ensure you have the following items to start making coffee: + +- An electric coffee maker +- Access to a power outlet +- Fresh coffee beans +- Burr grinder (if your beans are not pre-ground) +- Coffee filters (if applicable) +- Fresh water + +## Steps + +### Set Up Your Coffee Maker + +#### Unpack and Clean + +Unpack your coffee maker and wash all removable parts with warm soapy water to ensure there are no residues from manufacturing. + +#### Assemble and Plug In + +Follow the manufacturer's instructions to assemble your coffee maker and plug it into an electrical outlet. + +### Brew Your First Cup + +#### Measure and Grind Coffee + +Measure 15 grams of coffee beans per 250 ml of water. Use the grinder to achieve a medium grind, suitable for your machine. + +#### Add Water and Coffee Grounds + +Fill the reservoir with fresh water and place the ground coffee in the filter. + +#### Start Brewing + +Turn on the coffee maker and select your desired settings (if available). Wait until the brewing process completes. + +## Next Steps + +Congratulations on brewing your first cup of coffee! Now explore these additional features and techniques to enhance your coffee experience: + +- [Perfecting Your Coffee Grind](https://www.yourwebsite.com/coffee-grind) +- [Maintaining Your Coffee Maker](https://www.yourwebsite.com/maintenance-tips) + +Explore our [Video Tutorials](https://www.yourwebsite.com/video-tutorials) for visual guides on making various types of coffee beverages. + +## See Also + +- [Coffee Recipes](https://www.yourwebsite.com/coffee-recipes) +- [Troubleshooting Common Issues](https://www.yourwebsite.com/troubleshooting) \ No newline at end of file diff --git a/templates/getting-started/guide-getting-started.md b/templates/getting-started/guide-getting-started.md new file mode 100644 index 000000000..93512c19f --- /dev/null +++ b/templates/getting-started/guide-getting-started.md @@ -0,0 +1,155 @@ +# Getting Started Guide + +> Thank you for downloading this template from The Good Docs Project! Before using the template, read this template guide for information about how to complete each section. Want to explore more templates? Check them out in our [templates GitLab repository](https://gitlab.com/tgdp/templates). + +## Introduction + +A getting started guide introduces your users to your application for the first time. +It focuses on the **primary feature** of the application and helps your users to start using the application as quickly as possible. + +A good quickstart answers the following questions: + +- Scope: + - What is the core purpose of this application? + - What is the minimal use case that is covered in this quickstart? +- Install (if applicable): + - How do I download, install, and configure the application? + - How can I get any required access keys or authentication credentials? +- Hello World: +:memo: A hello world approach is the simplest and easiest task through which your user can get an end-to-end sense of how an application works. It also serves as a sanity check. + - How can I run a simple workflow for a core feature or a common use case? +- Next steps: + - What other features are available to explore in the application? + +Getting Started guides are often confused with getting started and marketing guides. Though these documents help the users get acquainted with the application, they widely differ in their target audience. The following table describes the differences: + +| |Getting Started Guide|Getting Started Guide| Marketing Guide| +|--------|----------------|----------------------|---------------| + |Target Audience|Domain experts who know the problem space|Beginners who are new to the problem space and the product|Business decision-makers who need to make strategic decisions such as whether to buy the product +|Content|Minimal conceptual information|Detailed conceptual information on product/domain| No/less conceptual information; instead focuses on the benefits and the customers using the product +|Focus|How-to| How-to and why| Sales + +## Why do I need a getting started guide? + +A getting started guide is often the first opportunity for your users to form a positive impression on your product, and form an opinion on the technology it was built on. It can: + +- Make users comfortable using the application. +- Motivate the users to take up more complex tasks. +- Reduce users' onboarding time and give them the feeling that the application is easy to use. +- Improve the user experience, and help reduce costs by lowering the number of support requests. + +## Before writing a getting started guide +Before you start working on your getting started guide, identify: +- The primary feature of your application. +- The quickest and the easiest way to implement end-to-end the primary feature of your application. +- A use case that your user can complete within 1 - 2 hours with a preference for a shorter time. +- The audience, as it helps the users determine if the getting started guide is relevant for their use. + +## Best practices for writing a getting started guide +- Lengthy getting started guides can overwhelm users. Consider condensing or removing steps or reevaluating the scope of the getting started guide. +- Avoid complicating the getting started guide by including error scenarios or complex use cases. +- Remove the burden of setup requirements as much as possible through sandbox accounts. +- Ensure that the getting started guide works and provides the advertised result. +- For code samples, ensure that you include: + - Any required `import` or `using` statements. + - Code comments that explain what the code does. + +## About the "Overview" section + +Use this section to provide the following: + +- A short description of your application and its purpose. +- A description of what the user can accomplish in this getting started guide. +- The intended audience for this document. +- The basic knowledge that you expect the user to have before using this getting started guide. + +## About the "Before you begin" section + +This section is optional. + +Use this section to mention any requirements/configuration prerequisites that the user must complete before they start the getting started guide. +For easy understanding, consider classifying the prerequisites into different categories such as software prerequisites, hardware prerequisites, and so on. + +## About the "Install" section + +This section is optional. + +:memo: Not all getting started guides require an installation section. Include this section if: + - Installation and/or configuration is done at the same time, and by the same person running the getting started guide. + - Installation of specific software(s) is a prerequisite to running the getting started guide. + +The purpose of this section is to provide instructions to your users on how to install and configure a particular software/tool before running the getting started guide. + +:memo: This section may not be relevant for Cloud/API-based applications where authorization and authentication information is more applicable. + +Use this section to provide: +- Basic instructions and commands to install your application. + - Always validate the commands and check for technical accuracy with your engineering team. + - Provide instructions to verify that the installation is successful. +- Link to the detailed installation guide if you do not provide installation instructions. +- Links to the upstream docs for common software installation instructions. + +## About the "Steps" section + +The steps section is where you describe what the user needs to do. How you write your steps will vary depending on your organization's style guide. +This template breaks down the getting started guide into parts. One part of the getting started guide may focus on completing several related steps. You're welcome to follow this structure or use the step headings on their own. + +If your getting started guide involves many complex tasks, break it down into different logical parts with each part consisting of one or more related steps. For example, you can structure a getting started guide to onboard an app as follows: + +Part 1 Configure your local dev environment + +Step 1.1 + +Step 1.2 + +Part 2 Build your app + +Step 2.1 + +Step 2.2 + +Part 3 Deploy your app + +Step 3.1 + +Step 3.2 + +Part 4 Test your app + +Step 4.1 + +Step 4.2 + +However, if your getting started guide does not involve many independent tasks, only add the logical steps. For example, you can structure a getting started guide to create a new project in Visual Studio as follows: + +Step 1 Create a new project + +Step 2 Select a template type + +Step 3 Configure your new project + +### Tips for writing steps in a getting started guide + +- Number the steps in the format {part}.{step} as it helps your users to easily identify and locate procedures in the getting started guide. Also, this helps in referencing a particular step in a lengthy getting started guide. +- Start the heading with a verb and express the step/part headings as a complete thought. Don't use the *-ing* form of the verb because it is harder to translate. For example, you could use the heading **Connect to the VM instance** instead of **Connect**. +- For each step, provide some background information about the task so users know what they're about to do and why. For example, while selecting a template for your Visual Studio project, you can provide details on the purpose of choosing a template and the different types of templates available in Visual Studio. +- Remember to orient your users when walking them through each step. If they need to open a particular file or dialog to complete the task, provide that information first. +- Provide examples of sample output such as return data, a message so that the users can validate that they performed the step correctly or not. +- Use plain language and define the terminology of any technical term next to it. +- Include one action in a step. + +:information_source: For additional tips on writing steps, see [Writing Procedural Steps](writing-tips.md#writing-procedural-steps) from The Good Docs Project. + +## About the "Next steps" section + +- Use this section to provide links to other tutorials/articles that the users can try on completing the getting started guide. +- Consider a logical connection from the current getting started guide that can act as a basis for your users’ next learning. +- (Optional) Provide links to relevant resources, like blogs, reference docs, videos, how-tos, and so on under a new heading **See Also**. + +## References + +* [What is a quickstart to you?](https://ffeathers.wordpress.com/2018/10/08/what-is-a-quickstart-to-you/) + +--- + +> Explore other templates from [The Good Docs Project](https://thegooddocsproject.dev/). Use our [feedback form](https://thegooddocsproject.dev/feedback/?template=Quickstart%20guide) to give feedback on this template. \ No newline at end of file diff --git a/templates/getting-started/template-getting-started.md b/templates/getting-started/template-getting-started.md new file mode 100644 index 000000000..bb60848bd --- /dev/null +++ b/templates/getting-started/template-getting-started.md @@ -0,0 +1,91 @@ + + +# Title + +> If you need more information about how to fill in this template, read the accompanying [guide](./guide-quickstart-template.md). + +> This template includes writing instructions and boilerplate text that you can customize, use as-is, or completely replace with your own text. This text is indicated in {curly brackets}. Make sure you replace the placeholders with your own text. + +## Overview + +This quickstart guides you through: + +- [Part 1](#part-1-task-name) +- [Part 2](#part-2-task-name) +- [Part n](#part-n-task-name) + +:information_source: (Optional) Link each part to its corresponding section for easy access. + +It is intended for {audience}. It assumes that you have basic knowledge of: +- Concept 1 +- Concept 2 +- Concept 3 + +:information_source: Link each concept to its corresponding content that helps users understand the concepts and ideas behind your software. + +## Before you start + +:information_source: This section is optional. + +Before running this quickstart, complete the following prerequisites: + +- Prerequisite 1 +- Prerequisite 2 +- Prerequisite 3 + +## Install + +:information_source: This section is optional. Use this section to provide installation instructions. + +## Part 1: {Task name} + +:information_source: Use this section to summarize what users complete in the following steps. + +### Step 1: {Step name} + +:information_source: You can use this format to describe your step: + +Explanatory text + +(Optional) Code sample or screenshot that helps your users complete this step. + +(Optional) Result on completing this step. + +#### (Optional) Sub step 1: {Substep name} + +:information_source: Beware of asking your users to do too much in one step. If needed, break a step into one or two smaller substeps. + +## Part 2: {Task name} + +... + +### Step 2: {Step name} + +... + +#### (Optional) Sub step 2: {Subtask name} + +... + +## Part n: {Task name} + +... + +### Step n: {Step name} + +... + +#### (Optional) Sub step n: {Subtask name} + +... + +## Next steps + +Now that you've completed this quickstart, try these to learn more about {feature}. +- Reference Link 1 +- Reference Link 2 +- Reference Link n + +--- + +> Explore other templates from [The Good Docs Project](https://thegooddocsproject.dev/). Use our [feedback form](https://thegooddocsproject.dev/feedback/?template=Quickstart) to give feedback on this template. \ No newline at end of file diff --git a/templates/how-to/example-how-to.md b/templates/how-to/example-how-to.md new file mode 100644 index 000000000..e01d3a3e1 --- /dev/null +++ b/templates/how-to/example-how-to.md @@ -0,0 +1,47 @@ +# Grind Coffee + + +## Overview + +This guide explains how to grind coffee beans to achieve the best flavour and consistency for your coffee. + + +## Before you start + +Before you begin grinding your coffee beans ensure: + +- You have fresh, high-quality coffee beans. +- A coffee grinder is available, either burr or blade. +- You understand the different grind sizes needed for various brewing methods. + +## Grinding Coffee + +Grinding coffee is essential to maximize the flavour extraction from coffee beans. The grind size needed varies based on the brewing method used. + +1. **Choose the right grinder:** Select a burr grinder for a more consistent grind or a blade grinder if availability is limited. +1. **Select the appropriate grind size:** Determine the grind size based on your brewing method. + 1. **Coarse grind** for french press or percolators. + 1. **Medium grind** for drip or filter coffee makers. + 1. **Fine grind** for espresso machines +1. **Measure your coffee beans:** Use a scale to measure your coffee beans before grinding. A general rule of thumb is 60g of coffee per 1000g of water, depending on your preferred strength. +1. **Grind your coffee:** Place the beans in your grind and grind them to your desired consistency based on the chosen grind size. +1. **Brew immediately:** Brew your freshly ground coffee immediately for the best flavour. + +### Adjusting Your Grind +If you find your coffee too weak or too strong, you might need to adjust the grind size: + +- A finer grind can increase extraction, leading to a stronger brew. +- A coarser grind decreases extraction, making the coffee weaker. + +### Espresso Grind Size +Espresso grind size is especially difficult to fine tune. See [How To Dial in Espresso](https://www.youtube.com/playlist?list=PLxz0FjZMVOl3ksLTyWsWNFdU1b73w1BUW) for a complete how-to. + + +## See also + + +- [Hoffmann Coffee Calculate](https://coda.io/@alessandro-mingione/hoffmann-coffee-calculator) - An easy way to calculate the amount of coffee to grind, based on James Hoffmann's ratios. +- [A Beginner's Guide to Coffee Grinders](https://www.youtube.com/watch?v=bgjvLQu5NlE) + + +--- diff --git a/templates/how-to/guide-how-to.md b/templates/how-to/guide-how-to.md new file mode 100644 index 000000000..a4cee3f2f --- /dev/null +++ b/templates/how-to/guide-how-to.md @@ -0,0 +1,173 @@ +# How-to guide + +> Thank you for downloading this template from The Good Docs Project! Before using the template, read this template guide for information about how to complete each section. Want to explore more templates? Check them out in our [templates GitLab repository](https://gitlab.com/tgdp/templates). + +## Introduction + +The how-to take your users through a series of steps required to solve a specific problem. It shows your users how to solve a real-world problem or complete a task in your application, such as how to create an issue in GitHub. + +**Note:** A task is an action that your users can do with your product to accomplish a goal. Multiple tasks may be involved in achieving a goal. + +The how-to clearly describes a set of sequential steps your users must complete to accomplish a task. The how-to assumes that a user has basic knowledge of the application and has already read the quickstart and the tutorial. + +Do not use a how-to to teach concepts. + +How-tos are often confused with [tutorials](https://gitlab.com/tgdp/templates/-/tree/main/tutorial). How-tos are task-oriented, while tutorials are learning-oriented. The table below identifies the differences between the two. + +| Tutorial | How-to | +| ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| Learning-oriented: Helps beginners or expert users learn a new feature in a hands-on way. | Task-oriented: Helps an expert user accomplish a task or troubleshoot an issue. | | | +| Follows a carefully managed part from the start to the end. | Aims for a successful result and guides the user along the safest, surest way to the goal. | +| Eliminates any unexpected scenarios and provides users with a successful finish. | Alerts the user to the possibility of unexpected scenarios and guides how to deal with them. | +| Assumes that users do not have any practical knowledge and must explicitly state any tools, file configurations, conceptual details, and so on. | Assumes that users have practical knowledge of tools, file configurations, applications, and so on. | + +## Why do I need a how-to? + +A how-to is often used to help advanced users perform a task correctly. It can: + +- Demonstrate to your users the different capabilities of your application. +- Guide your users to solve a real-world problem within the application through an ordered series of steps. +- Help answer specific questions that users may have. +- Make users comfortable using the application. +- Improve the user experience, and help reduce costs by lowering the number of support requests. + +New users can also benefit from a how-to, provided the how-to is well-written and states any prerequisite knowledge required to complete the task. + +## Before writing a how-to + +Before you start working on your how-tos, identify: + +- The main use cases for your application. +- The different scenarios that your user may encounter in the real world while completing a task. If this, then that. In the case of …, an alternative approach is to… +- The surest and safest way to complete a task. By suggesting multiple ways to complete a task, you're asking users to think through the different ways and choose. Save your users' time and effort by eliminating the options. +- The different error scenarios that a user may encounter while completing a task, and their corresponding solutions. + +## Best practices for writing a how-to + +- Address one logical goal (task) per how-to page. Try to avoid cases where only a subsection of the how-to is relevant to the user. +- Prepare your users for the unexpected, alert the user to its possibility and provide guidance on how to deal with it. For example, include callouts such as a warning, caution, or note to communicate important information while completing a task. +- Use conditional imperatives. If you want x, do y. To achieve w, do z. +- Do not explain concepts. +- Sometimes it's helpful to occasionally provide links to supporting pieces of documentation for more information.Especially, when the user might need a link to supporting background or [conceptual](https://gitlab.com/tgdp/templates/-/tree/main/explanation) information and/or [reference](https://gitlab.com/tgdp/templates/-/tree/main/reference) materials. However, avoid providing too many links within the guide. Keep your users on a single page as much as possible and provide links to additional resources at the bottom of the page. +- Avoid over-documenting multiple ways of achieving the same task. If there is more than one way to complete a given task, pick and only document the most common or recommended method of completing the task. Additional methods should be omitted or mentioned by providing a link or reference document. +- Avoid writing edge cases at the boundaries of your application's capability. +- Always ensure that the steps provided in your how-to guide are technically accurate. Test your how-to instructions from start to finish so that you can uncover omitted steps, incorrect details, steps out of order, and information gaps that block users. If it's not possible to test it yourself, have a developer or subject matter expert demonstrate the step to you and record the session, if possible. +- Re-test instructions after every notable product release to ensure instructions are still accurate and work end-to-end. +- Lengthy how-tos can overwhelm users. Focus only on one task in your how-to and restrict to a maximum of 8-10 steps per task. If the task is too big and complex, you may break down the task into multiple logical sub-tasks with their own steps. + +## About the "Overview" section + +Use this section to provide the following: + +- A clear description of the problem or task that the user can solve or complete. +- When and why your user might want to perform the task. For example, in a guide for creating a pull request, you might tell users that pull requests are used to let others know about the changes you have pushed to a branch on a repository. + +The how-to assumes that a user has basic knowledge of the application and knows what they want to achieve. + +Here are some examples: +- This guide explains how to create an issue on GitHub. You can create issues to track ideas, feedback, tasks, or bugs for work on GitHub. +- This guide explains how to resolve merge conflict using the command line. Merge conflicts occur when competing changes are made to the same line of a file. + +## About the "Before you begin" section + +{This section is optional} + +This section describes what your users need to know, or need to have before they attempt the how-to. By stating the requirements up front, you prevent your users from getting halfway through and discovering that they need to go and read other documentation before they can continue. + +Use this section to communicate any prerequisites for this how-to, such as: + +- Familiarity with the application +- Software and tools needed +- Environments to set up and configure +- Authentication and authorization information +- Other guides or information to read +- Links to procedures or information, or any useful pointers about how to get what they need. + +For easy understanding, consider grouping prerequisites into categories such as background knowledge and software prerequisites. + +Optionally, provide cues that signal to a user that they’re probably in the wrong place and offer more suitable options. For example, If you are a Linux user, refer to {link to relevant Linux how-to guide}. + +Here is an example: + +```markdown +Before you begin, ensure you have: + +- A conceptual understanding of RESTful APIs. + +Before you begin, ensure you have: + +- API credentials for the v3.5 API. +- Access to the Postman application. +- (Optional) A development environment (IDE) that displays API responses formatted for readability. +``` + +## About the "Steps" section + +The steps section is where you describe what the user needs to do. Use an ordered list structure to document the how-to steps. How you write your steps will vary depending on your organization's style guide. The template organizes the steps in the following way: + +``` +{Task name} + +{Optional: Provide a concise description of the purpose of this task. Only include this if the purpose is not clear from the task title.} + +1. {Write the action to take here. Start with a verb.} + + {Optional: Explanatory text} + + {Optional: Code sample or screenshot that helps your users complete this step} + + {Optional: Result} + +{Optional: If needed, you can add substeps below a primary step. Make sure to indent the substep one tab space over if you're using Markdown.} +``` + +Here is an example step: + +``` +Create pull request + +Pull requests are used to inform others of changes you have pushed to a branch in a repository. Once a pull request is opened, you can collaborate with reviewers and make changes before merging into the base branch. + +1. To create a pull request, do the following: + + 1.1. Navigate to the main page of your repository. + + 1.2. Under your repository name, click **Pull requests**. By default, all open pull requests are displayed. +``` + +If you're including code samples in your steps, make sure they are also indented correctly: + +1. Set your Git username for your repository. + + You can change the name that is associated with your Git commits using the `git config` command. + + ```bash + git config user.name "Dakota Everson" + ``` + +### Tips for writing steps + +- For task names, start with a [bare infinitive](https://en.wikipedia.org/wiki/Infinitive#English) also known as plain form or [base form](https://en.wikipedia.org/wiki/English_verbs#Base_form) verbs. For example, “connect”, “set up”, or “build” and express the heading as a complete thought. Don't use the -ing form of the verb because it is harder to translate. Instead of saying, "Connect", you might say, "Connect to the VM instance”. +- For each step, optionally provide some background information about the task so users know what they're about to do and why. Continuing with the example, you might provide some best practices for creating memorable repository names. +- Optionally, add a [code sample](https://developers.google.com/style/code-samples) or [screenshot](https://developers.google.com/style/images) after the explanatory text, depending on the type of how-to you're writing. Screenshots are a great way to show specific parts of the screen you are referring to in a step. Make sure your code samples work and are always up-to-date. +- Remember to orient your users when walking them through each step. If they need to open a particular file or dialog box to complete the task, provide that information first. +- Provide examples of sample output such as return data or a message so that the users can validate whether they performed the step correctly or not. For example, you might want to provide what a valid and expected result looks like on entering a command into a CLI. +- Use plain language and define the terminology of any technical term next to it. +- Include one action in a step. + +For additional tips on writing steps, see [Writing Procedural Steps](../writing-tips.md#writing-procedural-steps) from The Good Docs Project. + +## About the "See also" section + +It's likely that during explaining a multi-task process you will touch on other topics related to the current one, but not strictly required. This section is useful to provide your users with suggestions on further reading without interrupting the topic covered by the current document. An example might be setting up an email client, which requires working credentials for an active email address. The reader need not know how to install and run his/her email server to acquire that access, although this is potentially useful. The link to documentation on running a local mail server could therefore be included in the "See also" section. + +## Additional resources + +- Bhatti, J., et.al. 2021. [Docs for Developers: An Engineer’s Field Guide to Technical Writing 1st ed. Edition](https://docsfordevelopers.com/). +- [Diátaxis](https://diataxis.fr/). 2017. A systematic framework for technical documentation authoring. +- Carey, M., et.al. 2014. [Developing Quality Technical Information: A Handbook for Writers and Editors](https://www.amazon.com/Developing-Quality-Technical-Information-Handbook/dp/0133118975/ref=sr_1_1?crid=ZJR527VZPRL6&keywords=developing+quality+technical+information&qid=1662901229&sprefix=developing+quality+t%2Caps%2C196&sr=8-1). +- [Google Developer's Style Guide](https://developers.google.com/style/lists). + +--- + +> Explore other templates from [The Good Docs Project](https://thegooddocsproject.dev/). Use our [feedback form](https://thegooddocsproject.dev/feedback/?template=How-to%20guide) to give feedback on this template. \ No newline at end of file diff --git a/templates/how-to/template-how-to.md b/templates/how-to/template-how-to.md new file mode 100644 index 000000000..af42d3483 --- /dev/null +++ b/templates/how-to/template-how-to.md @@ -0,0 +1,58 @@ +# Title + +> If you need more information about how to fill in this template, read the accompanying [guide](./guide-how-to.md). + +> This template includes writing instructions and boilerplate text that you can customize, use as-is, or completely replace with your own text. This text is indicated in {curly brackets}. Make sure you replace the placeholders with your own text. + +## Overview + +This guide explains how to {insert a brief description of the task}. + +{Optional: Specify when and why your user might want to perform the task.} + +## Before you start + +{This section is optional} + +Before you {insert a brief description of the task}, ensure: + +- Prerequisite 1 +- Prerequisite 2 +- Prerequisite 3 + +## {Task name } + +{Optional: Provide a concise description of the purpose of this task. Only include this if the purpose is not clear from the task title.} + +{You can use this format to describe your steps:} + +1. {Write the step here. Use a verb to start.} + + {Optional: Explanatory text} + + {Optional: Code sample or screenshot that helps your users complete this step.} + + {Optional: The result of completing this step.} + +2. {Write the step here. Use a verb to start.} + + 2.1. {Substep 1} + + 2.2. {Substep 2} + +### {Sub-task} +... + +{This section is optional. Include a sub-task only if the task is big and complex.} + +## See also + +{Include references and/or links to other related documentation such as other how-to guides, conceptual topics, troubleshooting information, and limitation details if any. + +- Reference link +- Concept link +- Troubleshooting link} + +--- + +> Explore other templates from [The Good Docs Project](https://thegooddocsproject.dev/). Use our [feedback form](https://thegooddocsproject.dev/feedback/?template=How-to) to give feedback on this template. \ No newline at end of file diff --git a/templates/installation-guide/example-installation-guide.md b/templates/installation-guide/example-installation-guide.md new file mode 100644 index 000000000..0feccfc2c --- /dev/null +++ b/templates/installation-guide/example-installation-guide.md @@ -0,0 +1,142 @@ +# Coffee maker installation guide + +## Introduction + +This installation guide provides detailed instructions for setting up your new Nbeamex countertop coffee maker. Follow these steps to ensure a smooth installation and optimal performance. + +{Optional: Link to a demo video of the coffee maker in operation, or provide a sandbox environment for users to explore its features.} + +## Overview + +{This section is optional.} + +List the available versions of the coffee maker and link to their specific installation guides: + +| **Version**- | **Build**- | **Release date**- | **Status**- | +|--------------|-----------------|-------------------|-------------| +| V2.0 | Latest model | 01/04/2024 | Latest | +| V1.5 | Previous model | 15/08/2023 | Stable | + +{Briefly describe the outcome of the installation, such as the coffee maker being ready to brew or specific features being enabled.} + +## System requirements + +Ensure your kitchen has the following before starting the installation: + +- Adequate counter space +- Proximity to an electrical outlet +- Water supply for models with direct plumbing + +## Before you begin + +Before installing the Nbeamex coffee maker, make sure you have: + +- An appropriate location selected +- All included components (water reservoir, filter basket, carafe) +- Read through the safety instructions + +## Installation steps + +Follow these detailed steps to install your new coffee maker. + +### Prepare the installation area + +Ensure the area is clean and close to an outlet. + +#### Clear the countertop + +Remove any items where the coffee maker will be placed. + +#### Measure the space + +Confirm the coffee maker fits in the designated area with adequate clearance. + +### Set up the coffee maker + +Prepare your coffee maker for its first use by ensuring it is properly assembled, clean, and ready for operation. + +#### Unbox the coffee maker + +Carefully remove the coffee maker from its packaging. Place the coffee maker and all accessories on a clean surface. Make sure to keep all packaging materials for recycling or appropriate disposal. + +#### Wash the carafe and other removable parts + +To remove any manufacturing residues, wash the carafe, filter basket, and any other removable components with warm, soapy water. Rinse them thoroughly with clean water and dry them before assembly. + +#### Assemble the coffee maker + +Follow these steps to assemble your coffee maker: + +- Insert the filter basket into its compartment. +- Place the carafe on the warming plate. +- Ensure any lids or movable parts are securely fastened. + +#### Install the coffee maker on the countertop + +Position the coffee maker on a stable, flat surface near a power outlet. Ensure there is sufficient space around the coffee maker for air circulation and easy access during use. + +#### Plug in the coffee maker + +Connect the coffee maker to a power source by plugging the power cord into a suitable electrical outlet. Make sure the cord is neatly arranged to avoid any tripping hazards and not in contact with water. + +## Verify installation + +Run a water cycle without coffee to ensure the machine functions properly. + +## Post installation + +Register your coffee maker online to activate the warranty and receive updates. + +### Configuration options + +Adjust settings such as brew strength and water temperature according to your preference. + +### Upgrade options + +To keep your coffee maker performing at its best, upgrading the firmware is crucial. Follow these steps to upgrade the firmware: + +1. **Check firmware version**: Before proceeding, ensure you know the current firmware version of your coffee maker. This information can usually be found in the settings menu under "About" or "System Info." + +2. **Download firmware update**: Visit the Nbeamex support website and navigate to the 'Downloads' section. Select the latest firmware update for your coffee maker model. Download the firmware file to your computer. + +3. **Transfer firmware to coffee maker**: Connect the coffee maker to your computer using a USB cable, or use a Wi-Fi connection if your model supports it. Transfer the downloaded firmware file to the coffee maker's internal storage. + +4. **Initiate firmware upgrade**: Access the settings menu on your coffee maker and select the option to upgrade the firmware. Locate the firmware file you transferred and select it to begin the upgrade process. + +5. **Complete the upgrade**: The coffee maker will start updating its firmware, which may take a few minutes. Ensure not to turn off the coffee maker during this process. Once completed, the device will restart automatically. + +6. **Verify the firmware upgrade**: After the coffee maker restarts, check the firmware version to ensure the upgrade was successful. + +### Uninstallation options (preparing for return) + +If you need to return your coffee maker, follow these guidelines to ensure it is prepared safely and correctly: + +1. **Power off and unplug**: Make sure the coffee maker is turned off and unplugged from the electrical outlet. This is a crucial safety step to avoid any electrical hazards during handling. + +2. **Cool down**: Allow the coffee maker to cool completely if it has been used recently. This prevents any risk of burns when handling hot components. + +3. **Empty and clean**: Remove all contents from the coffee maker, such as water from the reservoir and coffee grounds from the filter. Clean the appliance thoroughly to ensure it is free of residues and odors. If the returned item is in poor condition, there may be issues with your return. + +4. **Disassemble removable parts**: Take apart removable components, such as the carafe, filter basket, and any other detachable parts. Clean each piece individually. + +5. **Pack securely**: Repackage the coffee maker and all its components in the original packaging if available. If the original packaging is not available, use a sturdy box with sufficient padding to protect the appliance from impacts during transit. Ensure that all parts are securely packed to prevent movement and possible damage. + +6. **Include all accessories and manuals**: Make sure to include all original accessories, manuals, and other materials that came with the coffee maker. Missing parts can complicate the return process and may result in additional charges. + +7. **Secure the box and affix a return label**: Secure the box with packing tape and attach a return label to it. Then schedule a pickup with a courier or take the package to a nearby shipping center. + +## Troubleshooting + +If you encounter issues during installation: + +- **Problem**- Coffee maker won't turn on. +- **Cause**- Not plugged in. +- **Solution**- Check the power cord and outlet. + +## Next steps + +Explore our [Coffee Brewing Guide](#) to learn how to make the perfect cup of coffee. + +## Definition of terms + +Provide definitions for terms used in the guide, such as "carafe" or "brew cycle." \ No newline at end of file diff --git a/templates/installation-guide/guide-installation-guide.md b/templates/installation-guide/guide-installation-guide.md new file mode 100644 index 000000000..f6f9d8333 --- /dev/null +++ b/templates/installation-guide/guide-installation-guide.md @@ -0,0 +1,157 @@ +# Installation template guide + +> Thank you for downloading this template from The Good Docs Project! Before using the template, read this template guide for information about how to complete each section. Want to explore more templates? Check them out in our [templates GitLab repository](https://gitlab.com/tgdp/templates). + +## Introduction +An installation guide covers all the steps necessary to install the product and set it up for further use. You need an installation guide to install: + +* Operating systems, applications, plugins, and extensions. +* SaaS (Software as a Service) applications. +* Open source software (OSS) product documentation. +* Hardware device product documentation. + +There are two categories of an installation guide: + +* **Standalone**: An independent installation guide document or page that includes all the necessary information required to install the software or application, including system requirements and step-by-step instructions. +* **Integrated**: An installation guide document or page integrated inside an existing README document. + + +## Identify your audience +An installation guide is for users who have the sufficient technical expertise required to understand the installation instructions provided. If your proposed audience requires some technical expertise to install the product, you should highlight and list these requirements in the prerequisites section of the document. + + +## Why do you need an installation guide? +An installation guide can: + +* Help a user get started using your product. +* Reduce the number of support requests related to installation issues. +* Establish consistency in the existing developer experience. +* Ensure increased retention of a user who explores your product. +* Confirm a user has everything they need to configure, customize, and/or upgrade your product. + +Installation guides are often confused with how-to guides. It is essential to distinguish between an installation guide and a how-to guide document. +​ +An installation guide shows how to install the product (as a procedure), while a "how-to" topic shows how to do something with the product after it's been installed. The difference lies in the purpose of the instructions. An installation guide describes the process of setting up and configuring a specific software, application, or service. A how-to guide describes how to accomplish a particular task using a specific product or technology (which would already be installed). +​ +The key differences are listed in the following table: + +| | **installation guide** | **how-to guide** | +| ------- | -------------- | -------------------- | +| Audience |Systems administrators and users who require detailed instructions and technical details when setting-up and installing a software product.| Users with a less technical background who want to set-up and install a software product. | +| Scope | An installation guide provides specific instructions on how to install and set up a particular software product. | A how-to guide takes the user through a series of steps required to perform a specific task to solve a particular problem. | +| Format | An installation guide is a prerequisite document a user reads before considering How-to Guides; because you need the product itself installed before you solve any problem related to that product. Due to the broad scope and availability of different variables and conditions in which an installation guide would function, an installation guide should be independent of a how-to guide. | how-to guide (or even a Tutorial) may include installation steps of the software or an application that needs to be installed as part of the How-to solution process. A hyperlink within the how-to guide would link back to the dedicated installation guide. | + + +## Before writing an installation guide +Before you start working on your installation guide, identify the following: + +* The target user who needs to follow your installation guide. This helps determine the appropriate level of information. +* The specific version of the software or application to be installed and the system requirements for installation. +* Software prerequisites or libraries dependencies. +* Installation options such as following an installation wizard or customized installation. +* Identify common issues that may arise during the installation process, and provide troubleshooting tips to help users overcome these issues. + + +## Writing the installation guide +This section provides details about writing the installation guide. + + +### About the “Introduction” section +In this section, state the purpose of the installation guide. Optionally, you can specify the benefits of this installation such as increased performance, better system stability, and enhanced security. +​ +Optional: add a link to a demo of the installed product or a sandbox to try out the product. + + +### About the “Installation types” section +In this section, explain what is included within the installation guide. This can include a list of different versions to be installed as an option. Make sure you highlight the differences between the installation scenarios. These can be outlined in a table with columns indicating the name of the installation type, a description of the installation type, and a link to the relevant installation steps within the guide. + +If your product can be used in different environments, include a table specifying the different installation types. This table can help users choose the relevant installation type based on their needs. For example, you can classify the installation type based on: + +* Main or lite version when a product has installable options with different functionalities. +* Operating system types such as installation for Windows, Linux, and MacOS. +* Cloud providers for products that require self-hosting to work such as CodeSpaces, CodeSandBox, and GitPod. + +Add an introductory sentence to the table. Also, include links for all the available options. | + + +### About the “Overview” section +In this section, explain the intended result of the installation, such as the commands, command aliases, major flags, available plugins, files downloaded, or application programs. + +Also, include a sequential end-to-end summary of the installation process that can serve as a quick link or reference section for users. Consider displaying this information in a table with one column summarizing the specific process and a second column linking to a relevant document. +​ +Optionally, you can include links to previous versions, if applicable. Consider formatting this list of versions in a table. + + +### About the “System requirements” section +In this section, explain the different installation types and subsequent requirements for each type. This section leads into the next section on specific prerequisites. + +Based on your use case, you can adjust the structure of this section by using it in reverse order. For example, you could list the installation type as the heading and system requirements for that type as a sub-section. For example, “Install on Linux > System Requirements” and “Install on Windows > System Requirements”, instead of “System Requirements > Install on Linux > Install on Windows.” + + +### About the “Before you begin” section +In this section, explain the prerequisites. Prerequisites tell the user what they require to accomplish a goal, such as: + +* Necessary dependencies or packages. +* Required version for your system or other system requirements. +* Specialist knowledge or skills. + + +### About the “Installation steps” section +​In this section, describe what the user needs to do to install the software. When writing this section: + +* Use numeric steps. +* Categorize the steps into subheadings, as required. +* Create subheadings based on the complexity of the installation. +* Add a one-sentence description of the step. +* Start each step with an active verb such as "open" and "download". +* Explain the expected result after completing each step. +* Include checks for success if each step is done correctly and/or tips if the installation didn’t work at each step. +* Mention installation options where required, but mention which path is recommended. +* Add visuals (GIFs, images, or videos) where required. +* Add code block examples and snippets where required. + + +### About the “Verify installation” section +In this section, include test commands, intended outputs, or other steps to confirm the installation was successful. + + +### About the “Post installation” section +In this section, provide an overview of options once the installation is completed. Include links to other relevant resources if available. + + +### About the “Configuration options” section +In this section, provide information regarding post-installation configuration options. Describe the requirements for configuring the installed product. Provide links to other resources if available. + + +### About the “Upgrade options” section +In this section, provide information about upgrade options (also known as an update options), if relevant. Describe how to install updates from a range of possible options. Provide a link to available updates with specific version numbers, release dates, and key features. + + +### About the “Downgrade options” section +In this section, provide downgrade options, if supported. + + +### About the “Uninstallation options” section +In this section, clearly describe the procedure to uninstall the product. + + +### About the “Troubleshooting” section +In this section, list a number of anticipated problems and associated solutions. This section helps solve problems encountered during installation. Start with a problem statement, then indicate the cause and provide a solution. Include any important additional information, such as restarting the computer. + +You can also include steps or contact information for additional support. + + +### About the "Next steps" section +In this section, include essential or recommended steps to take after installing the product. Provide links to further resources, if available. Also, include support/contact information for issue reports and feedback. + + +### About the “Product version history” section +​In this section, you can list previous versions in a table, providing the version number and whether the version was major, minor, or a patch release. Always ensure the change history is consistent across the documentation. Refer to [semver.org](https://semver.org) to learn about the semantic versioning specification. + + +### About the “Definition of terms” section +This section is optional. Provide a glossary table describing the terms, acronyms, and abbreviations used in the installation guide. + +--- + +> Explore other templates from [The Good Docs Project](https://thegooddocsproject.dev/). Use our [feedback form](https://thegooddocsproject.dev/feedback/?template=Installation%20guide%20guide) to give feedback on this template. \ No newline at end of file diff --git a/templates/installation-guide/template-installation-guide.md b/templates/installation-guide/template-installation-guide.md new file mode 100644 index 000000000..6536df29e --- /dev/null +++ b/templates/installation-guide/template-installation-guide.md @@ -0,0 +1,186 @@ +# Title + +> If you need more information about how to fill in this template, read the accompanying [guide](./guide-installation-guide.md). + +> This template includes writing instructions and boilerplate text that you can customize, use as-is, or completely replace with your own text. This text is indicated in {curly brackets}. Make sure you replace the placeholders with your own text. + +## Introduction +{The installation guide template includes information on writing procedures for successfully installing {product name}. {Insert your preferred description of the installation process.} + +{Optional: Add a demo GIF that shows what the installed project would look like or link to a sandbox or playground to test out the product and explore its features.} + + +## Installation types +This guide explains the steps and instructions required to install {product name} on supported operating systems. It also explains how to configure, start, and uninstall {product name}}. + +{Include a table to capture the different installation types, such as: + +* Supported operating systems +* The type of product installed (if provided in different versions, such as Main and Lite version) +* Cloud providers, such as CodeSpaces, CodeSandBox, GitPod, etc.,) including a link to the right heading for all options.} + +| **Type** | **Description** | **More information** | +| --------- | ----------------- | ------------------- | +| {Name of installation type} | {Description of installation type} | {Link to the relevant installation steps section} | +| {Name of installation type} | {Description of installation type} | {Link to the relevant installation steps section} | + + +## Overview +{This section is optional.} + +{Add a list of the available project versions, link to the installation guide for that version, and highlight the latest, beta, or stable version as listed in the following table:} + +| **Version** | **Build** | **Release Date** | **Status** | +| -------- | --------- | -------- | ------- | +| [V {versionNumber}](#link) | {versionNumber release} | {dd/mm/yyyy} | {Latest} | +| [V {versionNumber}](#link) | {versionNumber release} | {dd/mm/yyyy} | {Beta} | +| [V {versionNumber}](#link) | {versionNumber release} | {dd/mm/yyyy} | {Stable} | + + +{Explain the intended result of the installation, such as the commands, command aliases, major flags, available plugins, files downloaded, or application programs.} + +{Add a sequential end-to-end summary of the installation process that can serve as a quick link or reference section for users as listed in the following table:} + +| | **Process** | **More information** | +| ---- | ------------ | -------------------- | +| 1. | Before installing, check the system requirements to ensure your computer is supported in the latest version of {product name}. | {Link to relevant documents} | +| 2. | Check the system prerequisites to install all the required {software, dependencies, tools.}. | {Link to relevant documents} | +| 3. | {List additional steps.} | {Link to relevant documents} | +| 4. | Verify that the installation was successful. | {Link to relevant documents} | + + +## System requirements +{Start by breaking this into sub-sections based on the number of installation types (product type, operating system, or cloud—especially for projects that require self-hosting to work). Based on your use case, you can use this section reversely by having the installation type as the heading and system requirements for that type as a sub-section.} + +{Mention for all installation types.} + + +## Before you begin +{List and highlight all the required prerequisites here. Consider making this a table.} + +Before installing {version number}, ensure you have: + +* {Prerequisite one} +* {Prerequisite two} +* {Prerequisite three} + +{Include prerequisites for all installation types.} + +| **Type** | **Prerequisites** | **Note(s)** | +| --------- | ----------------- | ------------ | +| {Installation type name} | {Installation type prerequisites} | {Important considerations} | +| {Installation type name} | {Installation type prerequisites} | {Important considerations} | + + +## Installation steps +The following procedure explains how to install {installation type name} and {optional version number}. + +{Provide a short introduction to the step-by-step procedure based on the installation type.} + +Get started with {version number} by {write the first step a user needs to start the installation. Use a verb to start.} + + +### Step 1 - One-sentence description of the step +{Optionally, introduce this section with brief explanatory text.} + +{Continue with a list section if these steps include a sequence of instructions} + +{Optional: include a code snippet or relevant screenshot that helps your users complete the steps.} + +{Optional: show the result of completing this step, such as a text output or an image).} + + +#### 1.1. Substep 1 - One-sentence description of the step +{Optionally, introduce this section with brief explanatory text.} + +{Continue with a list section if these steps include a sequence of instructions} + + +#### 1.2. Substep 2 - One-sentence description of the step +{Optionally, introduce this section with brief explanatory text.} + +{Continue with a list section if these steps include a sequence of instructions.} + + +### Step 2 - One-sentence description of the step +{Optionally, introduce this section with brief explanatory text.} + +{Continue with a list section if these steps include a sequence of instructions.} + + +## Verify installation +{Include test commands, intended outputs, or other steps to confirm the installation was successful.} + + +## Post installation +{Provide an overview of options or link to other relevant documentation once installation has been completed. Also, account for anticipated problems during or after installation.} + +{Optinal: include short introduction text.} + + +### Configuration options +{Provide information regarding post-installation configuration options.} + +{Describe the requirements for configuring the installed product.} + +{Link to relevant documentation if needed.} + + +### Upgrade options +{Provide information regarding upgrade options, also known as an update options.} + +{Describe how to install updates from a range of possible options.} + +{Provide a link to available updates with specific version numbers, release dates, and key features.} + +Example: To begin the system updates: + +1. Choose the version number. +2. Download the update at [link](http://example.com). +3. Double-click the update file. +4. Additional steps as needed. + + +### Downgrade options +{Provide information regarding downgrading the version installed.} + + +### Uninstallation options +{Provide information regarding uninstalling the product, software, SDK, package, library, framework installed.} + + +## Troubleshooting +{This section helps solve problems encountered during installation. Start with a problem statement, then indicate the cause and provide a solution. Additional information can be added (e.g., restart the computer)}. + +{Add a warning note and highlight in color if the action has the potential to affect security. + +Communicating with the product engineers and programmers is essential to keep this section up-to-date.} + +{Problem: ...} + +{Cause: …} + +{Solution: …} + +{Support/contact information for issue reports and feedback.} + + +## Next steps +{Include what to do after a successful installation, such as a recommended next step or links to further recommended documentation.} + + +## Product version history +{History section with major changes to the installation guide tabulated following the Major.Minor.Patch semantic versioning specification.} + + +## Definition of terms +{Optional: Provide a glossary table describing the terms, acronyms, and abbreviations used in the installation guide.} + +| **Term** | **Meaning** | +| ------------------------------------- | ------------ | +| {Term, acronym, or abbreviation} | {Provide a definition of the term or acronym or abbreviation used in this guide.} | +| {Term, acronym, or abbreviation} | {Provide a definition of the term or acronym or abbreviation used in this guide.} | + +--- + +> Explore other templates from [The Good Docs Project](https://thegooddocsproject.dev/). Use our [feedback form](https://thegooddocsproject.dev/feedback/?template=Installation%20guide) to give feedback on this template. \ No newline at end of file diff --git a/templates/reference/example-reference.md b/templates/reference/example-reference.md new file mode 100644 index 000000000..3fe44d48b --- /dev/null +++ b/templates/reference/example-reference.md @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/templates/reference/guide-reference.md b/templates/reference/guide-reference.md new file mode 100644 index 000000000..3cfbc6862 --- /dev/null +++ b/templates/reference/guide-reference.md @@ -0,0 +1,43 @@ +# The reference article + +> Thank you for downloading this template from The Good Docs Project! Before using the template, read this template guide for information about how to complete each section. Want to explore more templates? Check them out in our [templates GitLab repository](https://gitlab.com/tgdp/templates). + +Reference articles provide information-oriented descriptions of specific components or characteristics of your product. +The purpose of a reference article is to concisely present information as a structured set of entries, with little to no procedural or instructional content. + +A reference article works well when it: + +* is consistent in structure, terminology, and tone. +* contains concise, descriptive information that is relevant to its overview +* avoids high-level usage-instructions or description for the product as a whole + +## Content of your reference article + +### The Overview section + +Summarize what this reference article is about. + +* Explain what all the entries defined on the page have in common. + +### The Body section + +The structure of reference articles varies based on what kind of information you are documenting. Formats that permit structured presentation of entries are best: tables, lists, interactive object-schemas, etc. +In most cases, reference information is easiest to express as a table. + +Use the "don't repeat yourself" (DRY) method and re-use content if it's written for the same audience, and it fits within your reference document without modification. + +### Code-generated documentation + +Reference documentation can often be auto-generated from source code and/or comments within the code. It is typically easier to keep auto-generated docs current, accurate and complete, as the documentation is maintained next to the code it describes. +Ensure code-generated documentation is thoroughly written. +This is important for API reference docs and package descriptions documented in code doc-blocks or produced with tools such as the Open API tool chain. + +## Reference article examples + +* **Example 1**. + +* **Example 2**. + +--- + +> Explore other templates from [The Good Docs Project](https://thegooddocsproject.dev/). Use our [feedback form](https://thegooddocsproject.dev/feedback/?template=Reference%20guide) to give feedback on this template. \ No newline at end of file diff --git a/templates/reference/template-reference.md b/templates/reference/template-reference.md new file mode 100644 index 000000000..a76efc8e1 --- /dev/null +++ b/templates/reference/template-reference.md @@ -0,0 +1,29 @@ +# {reference article title} + +> If you need more information about how to fill in this template, read the accompanying [guide](./guide-reference.md). + +> This template includes writing instructions and boilerplate text that you can customize, use as-is, or completely replace with your own text. This text is indicated in {curly brackets}. Make sure you replace the placeholders with your own text. + +## Overview +{Document author tip: +Summarize what this reference article is about. Explain what all the entries defined on the page have in common. What you put here is reused in the Overview section of your doc site and included in HTML description tags. For help with writing and structuring a reference article, see the file about-reference.md in this directory. Check out https://www.markdownguide.org/basic-syntax/ if you need help with markdown syntax. +} + +{Document author tip: It can be helpful to split up your reference page into subsets of related enries. For example, the reference page for an API endpoint might include subsets of entries for "General Requirements", "Request Parameters", and "Responses". The formats of entries might be different for each subset; for example, "General Requirements" might be a bulleted list, while "Request Parameters" and "Responses" are tables. +} +## {subset of reference entries} + +{table or other structured presentation of entries} + +{Document author tip: Here is a starter table for a subset of entries for parameters.} + +## Parameters + +|Name |Type |Required |Description | +|:--- |:--- |:--- |:--- | +|productCode|`string`|Yes|Code of the document product to return the schema for.
  • Here is a bulleted list with a \| (pipe) inside a table.
  • Another bulleted list.
    • An indented list
  • Back to the list.
| +||||| + +--- + +> Explore other templates from [The Good Docs Project](https://thegooddocsproject.dev/). Use our [feedback form](https://thegooddocsproject.dev/feedback/?template=Reference) to give feedback on this template. \ No newline at end of file diff --git a/templates/release-notes/example-release-notes.md b/templates/release-notes/example-release-notes.md new file mode 100644 index 000000000..60d8341b2 --- /dev/null +++ b/templates/release-notes/example-release-notes.md @@ -0,0 +1,53 @@ + +These release notes list and describe the new features, enhancements, and resolved issues in Nbeamex Coffee. + +## 2.16.0 + +April 18, 2024 + +### Upgrade guide + +If you are already using a previous version of Nbeamex coffee, please make sure to clean your grinder and coffee maker thoroughly before adding the new coffee beans. This will ensure that you get the best flavor from the new beans. + +{{< see-also >}}Please consult or [list of authorized retailers](https://nbeamex.com/retailers) to find the best coffee beans for your grinder.{{< /see-also >}} + +### What's new + +This release includes the following updates: + +- {{% icon-feature %}} **Using the latest coffee beans from the Nbeamex farm** + + We have sourced the best coffee beans from our farm and have added them to the Nbeamex Coffee. These beans are organically grown and have a rich flavor profile. + +### Changes to default behavior + +This release has the following changes to default behavior: + +- {{% icon-feature }} **Recyclable packaging** + + We have switched to recyclable packaging for our coffee beans. This change is part of our commitment to sustainability. + +### Resolved issues + +This release fixes the following issues. Select an issue's ID link to view its details. + +- {{% icon-resolved %}} Fixed an issue where the user would start shivering after the 8th cup [(1234)](https://nbeamex.com/issues/1234) + +- {{% icon-resolved %}} Fixed the issue where the grinder would not grind the beans[(5678)](https://nbeamex.com/issues/5678) + + +### Known issues + +You can find the list of known issues in the [Known issues](https://nbeamex.com/docs/known-issues) topic. + +### Security Updates + +{{< important >}} +For the protection of our customers, NBeamex doesn't disclose security issues until an investigation has occurred and a fix is available. +{{< /important >}} + +This release includes the following security updates: + +- {{% icon-resolved %}} **Secure bag vulnerability CVE-2024-9999** + + A vulnerability in the coffee bag ([CVE-2024-9999](https://coffee-sec.org/CVE-2024-9999)) could allow an attacker to steal the coffee beans. This issue has been resolved in this release. \ No newline at end of file diff --git a/templates/release-notes/guide-release-notes.md b/templates/release-notes/guide-release-notes.md new file mode 100644 index 000000000..15c6653da --- /dev/null +++ b/templates/release-notes/guide-release-notes.md @@ -0,0 +1,184 @@ +# Release Notes Template Guide + + Before using the template, read this template guide for information about how to complete each section. + +## Introduction + +Release notes communicate new features, improvements, bug fixes, and known issues to stakeholders such as customers, Technical Support, Sales, Marketing, and users. +This template guide and template are intended for customer-facing release notes, however, you can adapt it for internal release notes as needed. + +Stakeholders with both technical and non-technical backgrounds must understand what’s changed, and why those changes are important to the user. + +Release notes are usually published at the same time as a product or feature release. + +## Why do I need release notes? + +Release notes are important for the following reasons: +- They indicate transparency. Frequent release note updates show that you actively maintain the product and care about your stakeholders. +- They reduce support tickets. They keep your stakeholders informed about current releases, especially new features and known issues. +- They help your stakeholders assess impacts that might occur during upgrades. +- They provide a plain-language record of your software’s evolution. Stakeholders don’t have to read development-heavy changelogs to find out what’s changed and why it matters to them. + +The following table describes the differences between changelogs and release notes: + +| Release Notes | Changelogs | +|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Customer focused | Developer focused | +| Use plain language. | Use technical language. | +| Typically requires research to understand the features, functionality, and user experience. | Typically a light effort as it is closely related to developers’ current work. | +| Describes the changes to features and functionality.
  • Can include media to enhance descriptions.
  • Often includes links to the user documentation for more information.
    • | A reverse chronological list that describes code changes and their impact on the features.
    • Can include links to merge requests, issue numbers, or commits.
    • Can list contributors to the release.
    | +| Includes what changed and why. | Links to the developer who made the change and specific issues. | +| Typically written by a Technical Writer or Product Manager. | Typically written by a Software Developer derived from commit messages to a version control system. | + +## About this template + +The template includes the following sections common to release notes: + +- [Release Notes version](#release-notes-version): Include a document version number and a release date. +- [High-level summary](#high-level-summary-optional) (optional): One to two sentences that highlight the most important items in the release notes. +- [What's new](#about-the-new-features-section-optional) (optional): Describes new features and functionality. +- [Changes to default behavior](#about-the-changes-to-default-behavior-section-optional) (optional): Describes changes to default behavior. +- [Resolved issues](#about-the-resolved-issues-section-optional) (oprional): Lists the issues resolved in this release, if applicable. +- [Known issues](#about-the-known-issues-section-optional): Provides a link to a list of known issues. +- [Security updates](#about-the-security-updates-section-optional) (optional): Describes security updates in the release, if applicable. + +## Release notes best practices +- Write the release notes in a positive and friendly tone. +- Write in the second person. For example “Use your menu to access the window.” +- Be clear, concise, and consistent. +- Use plain language. +- Write in the present tense, except when you describe bug fixes; use the past tense for bug fixes. + +## Release Notes version +Each main section of your release notes should correspond to a product release number. +This helps stakeholders identify which release the notes are describing. +We use [semantic versioning](https://semver.org/) to number our releases. +This is usually shown as three numbers, separated by periods. +For example, 1.3.2. + +If the product publishes release notes off a release cycle, include the date in the subtitle, in `Month Day, Year` format. + + +## High-level summary (optional) + +A high-level summary can help stakeholders quickly understand the most important items in your release notes, especially if your notes are long. +Keep the summary short. + +## About the "New features" section (optional) + +List the most important features first. +What is important depends on your organization and stakeholder priorities. +Consider the features from the stakeholder’s point of view, and list new features that have the most impact on their experience first. + +When you write about new product features: + +1. Use an engaging, concise title to summarize the feature. +1. Describe how the feature benefits the stakeholder. You might ask yourself, “Why is this valuable? How does it benefit the business?” +1. Link to the feature’s full documentation in the description. The description in this section includes only a brief description. Link to the full documentation to provide a complete description, which becomes the source of truth. + +The following is an example of a new feature: + +- **Find Your Recent Transactions with Personal Log** + + Use Personal Log to quickly access your most recent transactions. + When speaking with a customer, you can select the last five transactions that you accessed from a menu. + You can also perform a more extensive search to find specific transactions you accessed in your queues. + See [Personal Log](http://example.com) for more information. + +The following formulas might be helpful when writing new features: + +**Formula 1:** + +- [ ] You can now {describe what you can do with the feature}. +- [ ] This means you can {benefit}. +- [ ] See {link to topic name} for more details. + + **If we were to apply this formula, using the previous example, it reads as follows:** + + You can now quickly access your most recent transactions. + This means you can select the last five transactions that you accessed from a menu when speaking with a customer. You can also perform a more extensive search to find specific transactions you accessed in your queues. + See [Personal Log](http://example.com) for more details. + +**Formula 2:** + +- [ ] {The application} now provides {feature}... +- [ ] …{benefit}. +- [ ] See {link} for more details. + + **If we were to apply this formula, using the previous example, it reads as follows:** + + Software X now provides a Personal Log, so you can quickly access your most recent transactions. + See [Personal Log](http://example.com) for more details. + + +## About the "Changes to default behavior" section (optional) + +Changes to default behavior are changes that affect the way the software behaves, but are not new features or bug fixes. +For example, if a default setting changes, you must communicate this to stakeholders. + +When you write about changes to default behavior: + +1. Use an engaging, concise title to summarize the change. +1. Describe how the change benefits the stakeholder. You might ask yourself, “Why is this valuable? How does it benefit the business?” +1. Link to the feature’s full documentation in the description. The description in this section includes only a brief description. Link to the full documentation to provide a complete description, which becomes the source of truth. + +The following is an example of a change to default behavior: + +- **New Default Setting for Notifications** + + Notifications are now enabled by default. + See [Notifications](http://example.com) for more information. + +The following formulas might be helpful when writing about changes to default behavior: + +**Formula 1:** + +- [ ] The {application or feature} now… +- [ ] …{describe the change}. +- [ ] See {link} for more information. + + **If we were to apply this formula, using the previous example, it reads as follows:** + + The Notifications feature now enables notifications by default. This means you will receive notifications for all new transactions. + See [Notifications](http://example.com) for more information. + +## About the "Resolved issues" section (optional) + +Resolved issues describe what was fixed and why it was useful to the stakeholder. +For example, if new fields are added to a database, you must find out how this helps stakeholders and communicate that information to them. + +When you write about resolved issues: + +1. Add the issue name (from the Known issues page). +1. Do not describe the issue or the fix. +1. Include the issue number and link to it in the Known issues list. + +The following is an example of a resolved issues: + +- Broken links in the user interface ([12345](http://example.com/known-issues/#12345)) + +## About the "Known issues" section (optional) + +The Known issues section provides a link to a list of known issues. We usually don't list known issues in the release notes because they are already documented in the Known issues list. + +## About the "Security updates" section (optional) + +The Security updates section lists resolved security updates in the release, if applicable. + +When you write about security updates: + +1. Add the security issue name. +1. Add the CVE number. +1. Describe the security issue and how it was resolved. +1. Link to the CVE number. + +The following is an example of a security update: + +- **Secure bag vulnerability CVE-2024-9999** + + A vulnerability in the coffee bag ([CVE-2024-9999](https://coffee-sec.org/CVE-2024-9999)) could allow an attacker to steal the coffee beans. This issue has been resolved in this release. + + +## Additional Resources + +See “[How to write meaningful release notes](https://drive.google.com/file/d/1q5GVhFEcUFzYxSkeOvzAyN9Gh0xPbAI-/view)” for additional ideas. \ No newline at end of file diff --git a/templates/release-notes/template-release-notes.md b/templates/release-notes/template-release-notes.md new file mode 100644 index 000000000..f3a56e6a8 --- /dev/null +++ b/templates/release-notes/template-release-notes.md @@ -0,0 +1,50 @@ +These release notes list and describe the new features, enhancements, and resolved issues in {Product Name}. + +## {version number} + +{date} + +{Optional: High-level summary} + +### (Optional) Upgrade Guide + + {Upgrade guide} + +### What's new + +- {%icon-feature %} **{Feature title}** + + {Feature description} + +### (Optional) Changes to default behavior + +This release has the following changes to default behavior: + +- {%icon-feature %} **{Feature title}** + + {Feature description} + +### (Optional) Resolved issues + +This release fixes the following issues. Select an issue's ID link to view its details. + +- {%icon-resolved %} {Issue title} [(Issue ID)](https://example.com/issues/{Issue ID}) + +### Known issues + +You can find the list of known issues in the [Known issues](https://example.com/docs/known-issues) topic. + +### (Optional) Security updates + +{{< important >}} +For the protection of our customers, F5 NGINX doesn't disclose security issues until an investigation has occurred and a fix is available. +{{< /important >}} + +This release includes the following security updates: + +- {%icon-resolved %} **{Security issue title} {CVE number}** + + {security issue description}. {CVE link}. + +--- + diff --git a/templates/style-guide.md b/templates/style-guide.md new file mode 100644 index 000000000..6ce174123 --- /dev/null +++ b/templates/style-guide.md @@ -0,0 +1,412 @@ + +# F5 NGINX Documentation style guide + +See the [revision history](#revision-history) for the current version. + +## Introduction + +Welcome to our project! This style guide is intended for use by project contributors, not necessarily end-users. It provides general guidance to anyone who contributes to the project's documentation. + +## Intended audience and scope + +This style guide is intended for use by any contributors that are writing documentation for F5 NGINX products, including software engineers. This guide can help project contributors to communicate clearly and consistently in the project's end-user documentation, API documentation, configuration files, and in-product user messages. + +## Our preferred style guide + +This document provides guidelines specific to documenting F5 NGINX products and open-source projects. + +When the NGINX style guide does not cover a style, refer next to the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) for user-facing content, and then to the [Chicago Manual of Style](https://www.chicagomanualofstyle.org/home.html). We use standard American spelling, and our preferred dictionary is the [American Heritage Dictionary](https://ahdictionary.com/). + +When writing documentation for our project, align with the default guide's voice and tone. + +## F5 brand trademarks and product names + +- On the first mention of an enterprise NGINX product in a document, use the full product name. For example: + + - F5 NGINX Plus + - F5 NGINX App Protect WAF + - F5 NGINX Instance Manager + +- Don't add "F5" to open source products. For example: + + - NGINX Unit + - NGINX Agent + +- For subsequent mentions of any enterprise product, you can drop the "F5". You must include the "NGINX" brand name in all uses. For example: + + - NGINX Plus + - NGINX App Protect WAF + - NGINX Instance Manager + +- When naming multiple products in one document, you only need to include F5 once, on the first mentioned product. +- Never use acronyms instead of the full product names. +- We don't need to use trademark and rights reserved icons (™,®) in product documentation. +- Use the full product name, including "F5" on product landing pages. +- Don't include the "F5" in document titles. For example: + + - Using NGINX Plus Docker images with NGINX Instance Manager + +- Don't use articles ("the", "a") in front of product names. For example, use + - NGINX Agent (not "the NGINX Agent"). +- Always use the full brand name in the meta description. The meta description does not count as first mention of the product in the document. + + +## Glossary of preferred terms + +The table provides guidelines about the terms you should and should not use for consistency, listed in alphabetical order: + +| Term | Notes | Explanation | +|------|-------|-------------| +| a.m./p.m. | 10 am. | | +| abbreviations: acronyms and initialisms, capitalization | Acronyms and initialisms are abbreviations that are written out in capitalized letters, but unless the word or phrase they represent is a proper noun, the words do not need to be capitalized. For example single sign-on (SSO). Note: acronyms are pronounced as words (such as LAN) but initialisms are pronounced as letters (such as SSO). | | +| abort | Never use this term in your docs. Use the preferred terms when writing about a process:
    stop
    interrupt
    shut down | Abort is acceptable to use in programmer or similar technical documentation only if it is a function name, parameter name, or otherwise part of a name in the API. | +| above and below | Avoid. Refer to the specific section, table, figure, an so on, as opposed to indicating its relative position in the document. | | +| access | Used as a verb, it's jargon, so don't use it.| | +| allows | Not recommended. \
    Avoid phrases such as "NGINX Plus allows you to…". \

    Use direct, active verbs from the perspective of the user instead. | | +| and/or | Not recommended. Usually, this means either "and" or "or". Try to be specific in your writing; people are counting on you for clear instructions. | | +| anthropomorphism | Avoid referring to the product or feature as though it were alive. \
    When referring to products, stay away from words like: decides, knows, sees, listens, and hears.
    A wizard guides you, it doesn't walk you through the steps. | | +| application | When referring to applications in general, write out the entire word. For clarity, avoid abbreviating to "app" unless specifically referencing the user interface or product. | | +| as/because | Use "because" instead of "as" when showing a cause-and-effect relationship. | | +| attack signature, attack signature set | Refers to elements of the NGINX App Protect WAF package. Do not abbreviate or otherwise shorten. | | +| backwards | Use backward and forward, not backwards and forwards | | +| black list
    blacklist
    blacklisted | Do not use these terms.
    Use these terms instead:
    -black list (noun) = deny list (noun)
    -blacklist (verb) = denylist (verb)
    -blacklisted (adjective) = denylisted (adjective) | | +| boot, boot up, reboot | Use "start" and "restart" if possible.
    For "boot", use in the context of "boot to a new volume". If the meaning is actually "start", then use "start". Do not use "boot up".
    Instead of "reboot", use "restart". \
    When referring to applying configuration changes, use "reload". | | +| case insensitive | Use "not case-sensitive" instead of "case insensitive". | | +| caution/warning | Caution is less severe than Warning. Use Caution when alerting that damage may occur, such as down time or service interruption. Use Warning as the severest form of advisory, such as the risk of data loss or sustained outage.| | +| certificate authority (CA) | | | +| certificate request | | | +| certificate signing request (CSR) | | | +| certificate/key pair | | | +| check (verb) | Do not use when referring to a checkbox action. Use select. Options for check as a verb: verify, confirm, test, ensure, and so on. | | +| checkbox (noun, GUI) | Use "select" when referring to a checkbox action.
    In this example, you could document as either: "For the Protocol Security (DNS) setting, select the Enabled checkbox." – OR – "For the Application Security setting, select Enabled." | | +| checksum | | | +| click vs select | Use "select". | Refer to the [Microsoft Style Guide instructions for Describing Interactions with UI](https://learn.microsoft.com/en-us/style-guide/procedures-instructions/describing-interactions-with-ui) for more information. | +| client certificate authentication | | | +| Client SSL | | | +| client-side or client side | Hyphenate when used as adjective. | | +| colloquial language | Try to avoid using colloquial language, which does not translate well. For example, use "press Esc", not "hit Esc"; "Go to the next section", not "jump to the next section". | | +| colon | Never use a colon to introduce a graphic, a figure, or a table. | | +| comma (serial or Oxford) | **Always use the serial (Oxford) comma.**

    Example: "apples, oranges, and bananas"; not "apples, oranges and bananas".| | +| comma-separated | Always hyphenate. For example: a comma-separated values (CSV) file | | +| command line and command prompt (usage) | Use "command line".

    NOUN: …at the command line.
    ADJ: …using command-line tools.
    At the command prompt, type...
    Do not use command-line prompt.| | +| configure | Do not use, except when describing the configuration of an NGINX product, such as when installing NGINX or NGINX Agent.
    In most cases, use "set up" instead.| | +| contractions | Contractions are okay to use as long as they're not ambiguous. | | +| Cookie persistence (option type) | | | +| cookie/cookies (noun) | | | +| covers | As in, "this section/topic/chapter covers the following...". Instead, use a phrase such as, "This topic deals with..." or "This topic provides the following information...". More options: communicates, presents, offers, introduces, explains, describes. | | +| curly brackets `{}` | The name for the curved `{}` parenthetical markings is "braces". They are not called curly brackets. | | +| CVSS v3.0 | Do not spell out. (Articles with CVSS metrics should include the CVSS link.) | | +| daemon | Avoid using this term in generic documentation because it is UNIX-oriented. Instead, we use "agent", "utility", or "application". However, we do refer to specific UNIX daemons, like `named` and `sod`, when daemon is part of the name. | | +| data center | Write this as two words. | | +| domain name | example.com, example.net, example.org, or localhost per [RFC 2606](https://www.rfc-editor.org/rfc/rfc2606.html). | | +| em dash | Allowed in the proper context. May be written using two dashes to ensure it converts correctly when displayed in the web version. | | +| data source | | | +| database | Do not abbreviate as "db". Always a single word. | | +| DoS/DDoS/3DoS | Spell out on first reference:
    - denial-of-service (DoS)
    - distributed denial-of-service (DDoS)
    - diverse distributed denial-of-service (3DoS) | | +| e.g., i.e., etc. | Avoid using Latin abbreviations.
    - e.g. = for example
    - i.e. = in other words
    - etc. = and so on | | +| earlier and later | Use to describe versioning. For example, "This applies to versions earlier than NGINX Plus R31".
    Do not use before, after, greater, lower, higher, below, above, and so on. | | +| either/or | Not recommended.
    Usually, we mean either, or we mean or. Try to be specific in your writing; people are counting on you for specific instructions. It's okay to use these terms when separated by text, as in, "You can use either the semi-colon or the comma here".| | +| ellipses […] | Don't use ellipses (dots) in your tech writing.
    When referring to a menu command that has an ellipse, DO NOT include the ellipse.
    It's okay to use the word "ellipses" in text. | | +| enable | Always use direct, active verbs.
    It's okay to instruct the user to enable a setting. Do not use in the context of a system or product enabling the user to do something.| | +| end a connection vs. tear down a connection (telephony) | In legacy telephony content, tear down was a clear way to describe how multiple connections were taken down (such as, for a trunk). Although that action is now completed in a streamlined and advanced manner (behind the scenes), end the connection may not be an accurate substitute phrase for this action, and suggest ending only one connection. | | +| Enter (key) | Do not use ALL CAPS when referring to the Enter key; use Initial capitalization. For example, Press Enter. | | +| enter (verb) | Follow MSG and use enter for data inserted into a box (field) or for a string that is likely to be blocked and copied. Use type for typing a command-line command. | | +| etc., i.e., e.g., etc., et cetera | Avoid Latin abbreviations. Be specific where possible. If the etc. represents additional information that the user needs to know, then include it. Otherwise, use and so on instead. You can recast to elaborate, or use that is if appropriate instead of i.e.; also use for example or for instance or such as instead of e.g., where applicable. | | +| EULA | End User License Agreement (EULA). A hard copy of the EULA ships with F5 products. | | +| example element (tagging) | Use the \ element when presenting a technical example of something (such as hardware/software and configuration details). If the information is not a specific technical example, or is further clarification of the subject, then a regular content paragraph is sufficient. | | +| executables | Refers to system files. Use system files instead. | | +| execute | Put to death. Don't use it. Use another word instead; for UNIX, we prefer run. Or start Alternatives: § Use the \ command to… § Enter the \ command at the prompt… § Start the \ utility… § Run the \ script… EXCEPTION: Security Advisory Articles and vulnerabilities in release notes. | | +| expand vs. flyout | Do not use flyout. Write text to describe action for the user. Expand is OK. | | +| expire | In GLOBAL-SITE and EDGE-FX documents, the term expire was used to take an object. It means to have the cache remove old content. We shouldn't have any need to use it this way anymore, thank goodness, as these products are gone. | | +| extraneous | Don't use it. Use extra or unneeded instead. | | +| F5 Networks (trademark practice) | Replace with "F5, Inc.". Visit the [trademarks page](https://www.f5.com/company/policies/trademarks) on f5.com for the latest guidance. | | +| F5 web resource URLs (reference) | Include the full URL when possible instead of masking the destination URL. Be sure to include the trademark in the URL name (unregistered trademark ™, or registered trademark ®, or service mark SM) at first mention where appropriate.
    For example: "In a browser, open the F5 Downloads page (https://downloads.f5.com)" or "the F5 DevCentral web site (https://devcentral.f5.com/)". | | +| F5 persona names | Do not refer to internal personae in public-facing documentation. | | +| F5 recommends vs. We recommend | Do not use We recommend or it is recommended when referring to an F5 recommended guideline. If needed, use F5 recommends or, at present, writers are encouraged to state the specific action that the user should take when possible. | | +| F5 Support | Use instead of F5 Technical Support or other variations thereof. | | +| F5 Technical Support | Do not use. Use F5 Support. | | +| F5 XC Tech Docs | Use when linking to documents on the https://docs.cloud.f5.com/docs/ site. | | +| fetch | This can be a technical term; depending on context, it may relate to getting, reading, or moving data objects. | | +| fictitious names (domains/companies) | When documenting example scenarios, unless it is a case study, and/or we have approval from the company to use their company name, we should use a generic fictitious approved name (such as ABC corporation or Company A or Company B). For domains, see [RFC 2606](https://www.rfc-editor.org/rfc/rfc2606.html) for reserved top-level DNS names to use in documentation. RE the GUI: Consult the legal team if your product team uses trademarked names (owned by others) in the GUI. | | +| figure captions (graphics) | Ensure that text describing the graphic is precise, short, and describes the action or process shown in graphic; do not include illustration in the caption. AVOID: “Figure 2 Illustration of NGINX Instance Manager using XXX. Avoid using trademarks in diagrams; instead, ensure that the product name is called out in the topic body text and add the trademark as needed at first mention. | | +| figures/images (TBA) | For a figure (screenshot or graphic): Use the \ content unit when you want to display a screenshot or a graphic on your topic. Within the \ content unit, use the \ element to contain the actual graphic, and use the \ element to provide a caption. For an image, such as an icon or button: Use the \<image> element to include artwork or images in a topic. In most cases, the \<fig> and \<title> elements are used. | | +| file name | File name is presented as two words, unless for commands/syntax or when matching the GUI, (representing variables) such as \<filename>. | | +| FIPS | Correct: FIPS hardware security module (HSM), FIPS HSM. | | +| flyout | Do not use. When describing the user interface, state that the "panel expands". | | +| foo bar, foo, fu, fubar | Do not use; always replace with specific text. Watch for these in code samples. | | +| forward slash | We don't call it a forward slash, just a slash. § In text, use as needed to match the UI, with no space on either side. Type the host name/IP address… § In syntax, the slash is used for web addresses: https://webmail.f5.com/exchange/ | | +| Forwarding (IP) | See virtual server types. | | +| Forwarding (Layer 2) | See virtual server types. | | +| forwards | Use backward and forward, not backwards and forwards. | | +| FTP | Do not spell out. | | +| fu, fubar | Do not use; always replace with specific text. Watch for these in code samples. | | +| future releases and TBD | Do not use TBD in any content, including release notes. Do not reference future releases, such as This OID will be disabled in future releases. | | +| G | Abbreviation for "giga", but in computer terminology represents 230, or 1,073,741,824. Correct: 4G | | +| Gateway ICMP | Also see ICMP | | +| GbE and GigE | For a number plus GbE, such as 10GbE, the standard is no space. For a number plus GigE, such as 10 GigE, the standard includes a space. | | +| gear icon | In a product's user interface, a gear icon may open an object's properties or the system settings. Refer to the object by its purpose, not the icon, unless in a task step. For example "Select the gear icon to open the system settings menu." or "Open the System Settings menu." | | +| geolocation vendor name (database) | Refer to geolocation vendor name as Digital Element versus parent company Digital Envoy. | | +| gerunds | Do not use gerund forms in article titles or headings. Correct: Provision your system. Incorrect: Provisioning your system. | | +| grayed out | Don't use it. Use unavailable. | | +| group box | Do not refer to UI element names if possible. Instead, use the label name. If necessary for clarity, use box. | | +| GSLB | This is the abbreviation for global server load balancing (GSLB). It is a subset of DNS. | | +| GUI | Do not use. Acronym for Graphical User Interface. Use "user interface" instead. | | +| hang | As in the system hangs or This hangs the system. OK in internal department stuff; but it's slang, and we should do better in our docs. For a write-around, try fail to respond, as in: If the program fails to respond, restart the system. Other possible terms to use, depending on the circumstances, could be: § causes the system to jam/get stuck/stop processing. § If horrid: halt, stop or crash; or cause an error. | | +| hardware upgrade | Hardware upgrade is to install a system in place with a newer platform. For example: Check the version compatibility list before upgrading your software to make sure you do not need to perform a hardware upgrade as well. | | +| has | One of those weak, vague verbs we're supposed to avoid as much as possible: Allow, do, enable, let, perform, be, has, make, and do. Use direct, active verbs instead. | | +| Headings | Use imperative verbs (formerly, MyF5 used gerunds) | | +| hears | When referring to products, avoid it, it's anthropomorphism. When referring to products, stay away from words like decides, knows, sees, listens, and hears. | | +| help (capitalization style) | When referring to online help in our documentation, use lowercase format for instances of help as per legacy guidelines (unless specifically referring to the Help button). However, identify it as F5 online help in order to distinguish it from general instances of help as a verb and noun. | | +| host name | Two words, except when a parameter. | | +| hover (user interface) | Use "hover over" not "hover on" nor "hover in" when describing this action. | | +| HTTP status codes | First mention: HTTP 200 status code (OK). Subsequent mention: HTTP 200 status code. HTTP status codes are grouped into five classes: 1xx (Informational): The request was received, continuing process 2xx (Success): The was successfully received, understood, and accepted 3xx (Redirection): Further action needs to be taken to complete the request 4xx (Client Error): The request contains bad syntax or cannot be fulfilled 5xx (Server Error): The server failed to fulfill an apparently valid request The following list is not exhaustive, but includes some common HTTP status codes: 100 Continue 101 Switching Protocols 200 OK 300 Multiple Choices 301 Moved Permanently 302 Found 304 Not Modified 307 Temporary Redirect 400 Bad Request 401 Not Authorized 403 Forbidden 404 Not Found 500 Internal Server Error 502 Bad Gateway 503 Service Unavailable 504 Gateway Timeout | | +| HTTPS | All caps unless appearing in URL, where it should be lowercase. A a daemon: https | | +| hyphens | You can use hyphens for compound words, to join prefixes to other words, or to show word breaks. Practice best judgment when employing them. In some instances, a hyphen may seem unnecessary as the compound word may be clear enough to the user and frequently presented without a hyphen, such as antivirus. In other cases, a term may look odd without it, so you may choose to include it for readability, such as pre-entrancy vs. preentrancy. Do not use hyphens to introduce list items in TBA content. | | +| i.e. | Latin abbreviation for "that is" or "in other words". Don't use it. | | +| id | When you mean ID, in text, never use user id nor user Id. If you're matching a UI that says one of these, talk to the Dev team about changing it to ID. | | +| ID | When you mean identify, in text, never use ID, spell out the word. | | +| if vs. whether | In informal writing and speech, often used interchangeably but can have different meanings, so try to use the correct word. Use if when expressing a condition of uncertainty: You don't know If NGINX Management Suite includes Instance Manager. Use whether when you are showing that two (or more) alternatives are possible: Whether your NGINX Management Suite deployment includes Instance Manager and API Connectivity Manager. | | +| in order to | Most often just use to instead, especially in procedures. | | +| information about vs. information on | Reserve the on preposition for location, such as The label on the back of the device... Use For information about NGINX Mangement Suite, refer to…. | | +| initiate | Use start instead. Press Enter to start the domino-fall routine. | | +| input | Not as a verb. Use type instead. | | +| insecure | Avoid using when describing a lack of security for something technical or technology-related, such as system versions, fraud issues, and so on. Across F5, we are trying to consistently use unsecure or not secure(though non-secure may appear as well) instead, for accuracy. | | +| interface and port (usage) | If referring to a physical port on F5 hardware, use interface (examples of interface names are 1.1, 1.2, and 2.1). In this case, port is just industry slang to mean a physical hardware interface. An actual port is a number that corresponds to a software service (daemon) running on a server, such as port 80, which corresponds to the HTTP service (and underneath it all, the httpd daemon). | | +| Internet, intranet, and extranet | Use internet to refer to the worldwide collection of networks that use open protocols such as TCP/IP to communicate with one another. Don't capitalize. Use intranet to refer to a communications network based on web technology, but that's available only to certain people, such as the employees of a company. Don't capitalize. Use extranet to refer to an extension of an intranet that uses internet protocols to give authorized outside users limited access to the intranet. Don't capitalize. | | +| interoperate | Do not use. Recast to operate or clarify connecting relationships as needed. | | +| IP address and MAC address | Specify whether referring to IP address or MAC address in content, rather than just address for clarity. IP and MAC are always capitalized. | | +| IP addresses (general usage) | Internal IP addresses that include beginning ranges, such as 172.25, 172.26, 172.27, 172.28, 172.29, 172.30, 172.31, and 172.32 should not appear in external documentation. | | +| IP addresses in examples | Be careful not to use example IP addresses that belong to another company. Refer to [RFC5737 for IPv4](https://www.ietf.org/rfc/rfc5737.txt) and [RFC3849 for IPv6](https://www.ietf.org/rfc/rfc3849.txt) for a list of IP addresses that are approved for use in documentation and examples. | | +| IPsec | Internet Protocol Security (IPsec), two caps. Note internal capitalization style of acronym. Do not use IPSec (three caps). | | +| IPv4-in-IPv6 vs. IPv4 in IPv6 | You can hyphenate IPv4-in-IPv6 when used as an adjective, such as IPv4-in-IPv6 tunnels. Note that the internal v in IPv4 and IPv6 should remain in lowercase format. | | +| ISO 9001:2015 certification | For example: ISO 9001:2015 certified" or ISO 9001:2015 certification Don't use: ISO certified or ISO certification (Per: ISO - Certification, for questions about the use of ISO Certificate terms and logo, please contact the GS quality team at *qmt) | | +| jargon | Jargon is the technical terminology or characteristic idiom of a special activity or group. Try hard to avoid it. Think about explaining something to a member of your family or a friend who doesn't know what you know. F5 products are highly technical, but strive to be as plainspoken as possible when describing or instructing. Spell out abbreviations on first use, use the clearest and easiest word to understand that will still accomplish the job, and so on. | | +| kill | Avoid this term except in command line syntax, where it is a UNIX command for stopping processes. (It's actually an IEEE POSIX standard command.) Alternatives for describing the action are: § End the process § Interrupt the process § Quit the process § Shut down the process § Stop the process | | +| known issue | Abbreviate as "KI" when using in public-facing documentation. | | +| knows | When referring to products, avoid it; it's anthropomorphism. When referring to products, stay away from words like decides, knows, sees, listens, and hears. Do not use possessive case for inanimate objects. | | +| Latin | Don't use it [via, vice versa, id est, i.e., e.g., etc. ] EXCEPTION: Security Advisory Articles and vulnerabilities in release notes. | | +| launch | As in launch a program. This is jargon. Use start instead. | | +| layer 4 (L4) | Lowercase spelled out, capitalized in abbreviation. Use same reference for all layer numbers: layer 2, 3, 7, etc. layer 4-7 (L4-7) (no spaces) | | +| left-hand | See Page directions. | | +| let | One of those weak, vague verbs we're supposed to avoid as much as possible: Allow, do, enable, let, perform; enter [usually implies type and press Enter], be, has, make, and do. Use direct, active verbs instead. | | +| lets, allows | Avoid. These verbs are system-focused and not user-focused. They may be appropriate to employ in a description about the feature, but not when describing what a user can accomplish by using the feature. | | +| list box | When possible, don't use the UI item name. Use the label name instead. If necessary for clarity, use list. | | +| listens | When referring to products, avoid it, it's anthropomorphism. However, it is acceptable only in conjunction with UNIX daemons, which listenon the port specified by a user. When referring to products, stay away from words like decides, knows, sees, listens, and hears. | | +| load balance, load balancing, load balancer | No hyphen, even as an adjective. | | +| local domain name system server vs. | Do not use; use local domain name system server or variations as applicable, such as local DNS server or LDNS server and so on. | | +| Log error message types (format) | The message type should be formatted in lowercase, such as: log_error. | | +| Log in syntax for products | *Login* is an adjective or noun. Log in is a verb. *Log in* to (F5 product) or verify your login credentials. | | +| login vs. logon | Use log in and log in to. There are still legacy instances of log on and logon and GUI references to logon. Do not use log into (or onto) when referring to the login process; use two words: Log in to the system… Login is an adjective or noun. Log in is a verb. | | +| lower left hand | See Page directions. | | +| lower right hand | See Page directions. | | +| make | One of those weak, vague verbs we're supposed to avoid as much as possible: Allow, do, enable, let, perform, enter [usually implies type and press Enter], be, has, make and do. Use direct, active verbs instead. | | +| man pages, MAN number | Man pages (short for manual pages) are OK to mention in content if appropriate. MAN numbers refer to the manual publication numbers that appear in the front matter of our documentation (such as MAN-0123-04). | | +| management interface | Synonymous for management port. | | +| management port | Synonymous for management interface. | | +| manually vs. “from scratch” | Use manually or specify when describing how to create a process from the beginning or at the start. Avoid from scratch to ensure clarity and prevent future localization issues. | | +| master | Do not use this term in documentation unless you are referring to/quoting specific command line syntax or process. For example: "The nginx master process...". Some possible alternatives, depending on your use case: primary, prime, principal, control, or, possibly, server. For more information, refer to K34150231: Exclusionary language in F5 products and documentation. | | +| master/slave | Do not use these terms if possible. Revise to primary/secondary. | | +| may/may not | Implies permission or uncertainty. Generally, use can indicate ability. | | +| menu | In general, try to avoid discussing the UI. Use the label of the UI item instead unless there is a possibility for confusion. Do not use menu as a generic term. Most often the UI item is a list, not a menu. Never use "drop-down menu". | | +| mouse | Don't use the word mouse when you mean cursor. | | +| mouse over | We don't use mouseover, or mouse over, or mouse-over in our writing. If you need this concept, try a write-around: "when you move the cursor over..." or "hover over the system performance graph...". | | +| Move button and \<< >> symbols (GUI) | When referring to GUI settings, you can document the button as the Move button and follow with the icon symbols \<< or >> as appropriate, or opt to not include the button by name if appropriate. | | +| multifactor authentication (MFA) | multifactor is one word | | +| mutually exclusive | Be careful how you use this. PREFERRED: This option mutually excludes the from-group and to-group options. TECHCOMM STYLE: The from-group and to-group options are mutually exclusive. | | +| My Support | two words, title caps | | +| MyF5 | Do not use MyF5 Knowledge Base (MyF5) or MyF5 portal. | | +| name server vs. nameserver | nameserver | | +| Navigate to | Replaces with "Go to". | | +| net | Don't use the word net to mean network. | | +| network | Don't use network as a verb. | | +| network mask | In our documentation, a network mask is also known as: a netmask,subnet mask, and mask. Use network mask when possible. | | +| Note style type | Use only these Note style types: Note, Important, Tip, and Warning. Caution and Attention note style types are not used unless in hardware documentation. We do not use Notice. | | +| numbers and numerals | Spell out the number 0-9, for example, three computers one file; numbers are OK to use in numeric elements (<0); ordinal numbers use words, such as first, second, third. Our hardware documentation may present some exceptions to this guideline. | | +| numeric ranges | Use a hyphen (or En dash if available) as opposed to writing to when possible to indicate a range between numbers. Use a hyphen as opposed to writing to when possible to indicate a range between numbers. Also use “between” when possible, and not from when referring the numeric range. MyF5 uses through instead of a hyphen in paragraph text (non-procedural writing or writing outside of titles, tables, headers, etc.) when indicating version ranges. NGINX Instance Manager 2.1 through 2.5. | | +| on-screen | Do not use screen or variations thereof when referring to the user interface. Use "page" instead. | | +| once | For localization purposes, use only in the noun form (to mean one single time). Use when or after as appropriate. Not our style: Once you have completed this task, the configuration is complete. | | +| operating system vs. operation system | Watch out! We run an operating system (OS) and perform an operation; do not use operation system for OS. | | +| output | Is a great word as a noun or adjective, but a failure as a verb. Use write to, display on, print on, or print to instead. | | +| page | Use instead of screen. | | +| page directions | Use only when necessary (when a UI item is hard to find). Consider that, due to Responsive Web Design, the directions may not be applicable on all viewing devices. <br>Use: at the top of the page, at the bottom of the page, on the right side of the page, on the left side of the page.<br>Avoid: right-hand, left-hand, above, below, and other variations | | +| patch | Use when applying an engineering hotfix. For example: You can patch your system using hotfix files. | | +| path | Try to avoid using it when referring to a directory structure. You may use path when you are referring to a DNS path. In DNS, path and directory structure are different things. Use path. | | +| path name | Don't use it. Use path instead (see path). Don't use path name, but you can use file name. | | +| percent (%) | Do not spell out percent. | | +| perform | One of those weak, vague verbs we're supposed to avoid as much as possible: Allow, do, enable, let, perform; enter [usually implies type and press Enter], be, has, make and do. Use direct, active verbs instead: complete, follow the steps, finish… | | +| persist | When used as a transitive verb, as in use this command to persist connections to the server. Use the adjective form, persistent, whenever possible. So instead of saying to ensure the connections persist, say "To ensure persistent connections...." | | +| please, thank you | Don't use please except where the user is asked to do something inconvenient or where the software is to blame for a situation. Use thank you only when user has provided info that is difficult or inconvenient to collect. | | +| plug-in, plugin | Both variations (with and without hyphen) are acceptable as long as maintaining internal consistency throughout topic(s) and/or sections, and clear to audience. | | +| pointer | On the off chance that we'll ever talk about a cursor, don't use the word pointer when you mean cursor. | | +| policing | Recast in terms of policies or policy enforcement for clarity, if appropriate. | | +| policy | Always qualify this with an appropriate modifier when referring to a policy, such as enforcement policy or access policy, and so on. | | +| Policy Builder | Do not use the Policy Builder or Policy Builder feature or any other permutations thereof. | | +| policy item | Policy items are the objects used to build policies in the Visual Policy Editor. Policy item names are title case, non-bold. For example, the SSO Resource Assign policy item. | | +| policy name (user instruction, tagging) | In a content example, such as: When creating enforcement policies that you plan to apply globally or to unknown subscribers, include the word global or unknown in the policy name to distinguish these from other subscriber policies. Do not use quotes for emphasis. | | +| popup screen, pop-up window | MyF5 uses pop-up window instead of dialog box. TechComm uses popup screen instead of dialog box. | | +| possessives | Don't do it with our trademarks. Do not use possessive case for inanimate objects. Do not use possessive constructions for product and company names, such as *NGINX's config file*. No possessive in trademarked words. For instance, you can't have the *NGINX's anything* but you can say the *NGINX instance's* something. | | +| power off | Do not use.* Use *shut down* for *turn off*. | | +| pre-logon | As a setting: Pre-Logon Sequence. | | +| prepositions | Areas--Settings are in an area of the page.<br>Box -- Users type in a box. <br>Charts -- Charts show on a page; info is found in charts. <br>Check box -- (use rarely) We place a check in a checkbox (more common, select the checkbox) <br>Diagram -- Info or objects are in a diagram or in a figure <br>Headers -- Users hover over a header. <br>Legend -- Users find info in the legend for a figure. <br>List -- Select (without preposition) an item in a list. Select an option from a list; data appears in a list. <br>Menu bar -- Select something on a menu bar. <br>Menus -- Commands are on menus. Menus -- Choose commands from menus. (Note: most UI elements are not menus but lists. See menu.) <br>Navigation pane -- Select an item in/on the navigation pane. <br>Network -- Printers may be on a network. <br>Pages -- Information and controls are on a page. <br>Panels -- Refer to objects in a panel. <br>Popup window –-(use infrequently) Information and controls are on a popup window. <br>Tabs -- The Visual Policy Editor may open in a new tab; information is found or selected on a tab. <br>Tables -- Controls are in, and info listed in, tables; but you select an item from a table. <br>Toolbar -- Select something from a toolbar, or tell the user to select something on the toolbar. | | +| private cloud | A cloud computing environment wholly dedicated to, and accessible only by a single group, or organization. Use instead of: bare metal on-prem. Also see public cloud. | | +| procedure vs. step | Avoid referring to a procedure as a step(s). We can refer to a procedure as a task if appropriate. | | +| pronouns | Second person (you, your) is preferred over third person (the user, the administrator) unless necessary to avoid confusion. Avoid we If possible, use F5 instead of we. Following MSG's Bias-free communications, use gender-neutral pronouns rather than he/she, his/hers, and him/her. If you can't write around using the pronoun, use their, theirs, they, or them for the gender-neutral singular and plural pronoun. | | +| public cloud | Cloud computing services delivered over infrastructure shared by multiple groups or organizations. | | +| QoS vs. QOS | Do not write as QOS regardless of the context; always document the abbreviation for Quality of Service as (QoS). | | +| queuing vs. queueing | Use queuing, not queueing. | | +| quotation marks | In our docs, we don't typically use quotation marks except when quoting a source, or when they are required for syntax. | | +| quotation marks (titles/headings) | Do not use quotation marks in topic titles or section headings; recast or omit if needed. Also, apply appropriate tags to identify what the text represents (such as a log or error message, and so on) rather than using quotes to add emphasis or convey something about the text origin. You can use smart (straight) quotes in release notes, for table cell content (such as CLI syntax and related text in Known issues, and so on). Do not use curly quotes in content. | | +| radio button | Don't use radio button. Refer to item by label. If necessary for clarity, use button or option. | | +| Reboot, reset | Do not use. Use restart. See boot, boot up, reboot. | | +| Referrer | (industry standard when referencing the referrer header.) | | +| regular expression | Not RegExp. | | +| Reject | See virtual server types. | | +| reject-all | Also refer to catch-all. | | +| replace | To install a system in place of one with the same platform, due to failure or similar condition. For example: If your hardware fails, you can replace it if you have a support contract by calling F5 Support. | | +| resource record | Not RR. | | +| Result (TBA and GUI) | For GUI content, you can omit a Result step if you feel the result of the GUI steps would be obvious and expected for the user. | | +| right-hand | See Page directions. | | +| Role-based Access Control (RBAC) | Note the hyphen and acronym style. | | +| root account | Use this version for general references; if referring to the UI, reflect how the UI refers to it. | | +| scale (up, down, in out) | See Autoscaling. | | +| screen | Do not use screen or variations thereof when referring to the product user interface. Use page instead. | | +| secure network address translation (SNAT) | SNAT is a noun. Do not use as a verb. You use SNAT to. You don't SNAT to. | | +| secure web gateway | Do not abbreviate generic references to the F5 offering. | | +| sees | When referring to products, avoid as anthropomorphism. When referring to products, stay away from words like decides, knows, sees, listens, and hears. | | +| select | Use instead of "click on" when referring to interaction with elements of a product user interface. | | +| server-side/server side | Hyphenate when used as an adjective. | | +| Session Initiation Protocol (SIP) | Correct: a SIP client (pronounced sip). | | +| shortcut menu | Don't use it. | | +| should | Should can be ambiguous. Avoid using it. Do not use should when you mean if. Don't say, Should you decide to … just say If you decide to… . | | +| single quotes | In our docs, we don't use single quotes to mean apostrophes [ 'like this' ]. We use them only when they are required for syntax. | | +| slash (“/” symbol) | When referencing the slash character (forward or backward) in content, specify the symbol by name (forward slash or back slash). You can also add the symbol if you feel that is helpful, though this is not required (/). Do not use oblique to mean slash. | | +| slave/master | Do not use these terms if possible. Revise to secondary/primary, respectively. For more information, refer to K34150231: Exclusionary language in F5 products and documentation. | | +| space | Do not use when referring to an input field or checkbox where the user needs to enter info. Recast to identify as a box. | | +| SPDY | Correct: a SPDY profile (pronounced speedy). | | +| spin up/spin down, spinning up/spinning down | Jargon, but becoming more widely used because of AWS. Do not use in our documentation without adding context on first reference. For example You can spin up (create additional virtual instances) or spin down (remove virtual instances) . . . . | | +| SSH | Do not spell out. | | +| SSL | Do not spell out. | | +| SSLi/SSL Intercept | For the SSL Intercept iRule. Spell out. Do not abbreviate except to match UI label. | | +| Sync-Failover (and Sync-Only) | Title capitalize and hyphenate to Sync-Failover unless referencing the option in tmsh; then lowercase and hyphenate as sync-failover. These guidelines apply to Sync-Only as well. | | +| tap | Describes action of touching the hardware touchscreens in hardware documentation. Do not use in software documentation; use "select" instead. | | +| tarball | tarball is defined as "files distributed as a tar archive"; a computer file format that can combine multiple files into a single, typically compressed, file. | | +| TCP flag names | All caps. SYN, ACK, PSH, URG, FIN, etc. (Industry standard) | | +| tense | Strive to use the simple present tense rather than the past or future, unless necessary for clarity. Do not: The system will receive. Do: The system receives. Do not: The feature was introduced in NGINX Instance Manger 2.16. Do: The feature is introduced in NGINX Instance Manager 2.16. (Remember that for some users older versions are used in the present.) | | +| text box | Use box. | | +| that vs. which vs. who | Be careful. Don't use *that* when you mean *who*. Use *that* for objects and *who* for people. Also, make sure you don't mean *which*. *That* sets off essential clauses (containing information essential to the meaning of the sentence). *Which* sets off non-essential clauses (not containing information essential to the meaning of the sentence). Examples: The virtual servers that you configured are ready. (*that you configured* is essential to distinguish them from virtual servers that you did not yet configure.) The virtual servers, which you configured, are ready. (*which you formatted* is not essential because you do not have any configured ones to distinguish the configured ones from. This is just extra, non-essential, information. Note: *which* and the clause it modifies are set off by commas because you could eliminate the clause without changing the meaning of the sentence. You can't do that with restrictive *that* clauses. | | +| third-party trademarks | Writers do not need to trademark third-party product names/companies in content such as topics, help, or release notes. In our copyright page, we include this statement: All other product and company names herein may be trademarks of their respective owners. Rationale: It is not required, and some third parties have guidelines explicitly requesting that their marks are not marked. If a specific vendor requests it, then we can. But generally, we should not. | | +| threshold event | We're not using this term in the documentation. The occurrence of system performance crossing a threshold and now behaving in a manner of interest to whoever established the threshold. A threshold event is generally associated with a notification. | | +| touchscreen | One word, used to describe new active screens in hardware displaying settings. | | +| trademarks | Watch out for possessive—don't do it in trademarks. For instance, you can't have the *NGINX's anything* but you can say the *NGINX instance's something*. Don't hyphenate trademarks. | | +| Traffic Management Microkernel (TMM) | First mention: the Traffic Management Microkernel (TMM)Subsequent references: the TMM | | +| Traffic Management Operating System (TMOS) | Do not use. See TMOS. | | +| typically vs. normally | When describing a predictable and expected action in technical content, write in terms of what is typical rather than normal for clarity. Normal implies judgment. Avoid particularly when applying to user actions, practices, or behaviors. Use typical instead. | | +| UDP | User Datagram Protocol. Do not spell out. | | +| UI/GUI/WebGUI | Don't use these terms in documentation. For UI, call it the browser interface or user interface if necessary. Don't use GUI, or WebGUI. | | +| unsecure and non-secure | Use unsecure and not insecure when describing a lack of security regarding something technical or technology-related in our documentation. If preferred and internally consistent with what you are documenting, non-secure may be OK, but defer to your editor. | | +| update | Use when moving from one minor version of a product to another. For example, from NGINX Instance Manager 2.1 to 2.2. For example: Before updating your system, you should read the release notes to understand any new issues. For example: OIDC-authenticated users can't view the Users list after updating to NGINX Instance Manager 2.9.1. | | +| upgrade | Use when moving from one major version of a product to another. For example, from NGINX Instance Manager 1.0 to 2.0. For example: When upgrading NGINX Instance Manager system, make sure your license key supports the new version. | | +| upper left hand | Don't use. See Page directions. | | +| upper right hand | Don't use. See Page directions. | | +| username | one word | | +| versions and version ranges | When referring to a software version, indicate the software name and then the version (for example, NGINX Instance Manager 2.16). Do not use the word version between the software name and the version (for example, NGINX Instance Manager version 2.x) When indicating a range of versions in procedure titles or subsection titles, indicate the software name and then the version range with a space, hyphen, and space between the version numbers (for example NGINX Instance Manager 1.x - 2.x). | | +| via | Do not use. Use by means of or through or recast in terms of using to ensure clarity of meaning and avoid confusion with Via Headers. (and because it is Latin.) | | +| vice versa | Another Latin word that we use like English. Avoid it; it's hard to translate. Instead, use conversely. | | +| virtual address | Use instead of virtual IP address or VIP. | | +| virtual address vs. virtual IP address | Although this refers to the IP address part of a virtual server destination address, only use virtual address (which also reflects the GUI). | | +| virtual edition/Virtual Edition | Use virtual edition as a generic term. For Virtual Edition, see VE. | | +| Virtual Local Area Network (VLAN) | Do not spell out unless necessary to context. | | +| Virtual Private Network (VPN) | Do not spell out unless necessary to context. | | +| walk | Don't use. Anthropomorphism. Instead, try guides, leads, conducts, directs, shows… Example: The Setup utility guides you through a series of pages. | | +| warning/caution | Caution is less severe than Warning. Use Caution when alerting that damage may occur, such as data loss. Use Warning as the severest form of advisory, reserved for when there's a hazard to personnel (such as you're being directed to install a server rack and there's a chance it may fall on you). | | +| wget | command.| | +| Wget | program. | | +| whether or not | Don't use whether or not something happens. Use whether. Also see if vs. whether. | | +| whitelist and blacklist, whitelisting and blacklisting | Do not use these terms. Use the following substitutions: white list (noun) = allow list (noun); whitelist (verb) = allowlist (verb); whitelisted (adjective) = allowlisted (adjective); black list (noun) = deny list (noun); blacklist (verb) = denylist (verb); blacklisted (adjective) = denylisted (adjective). <br> For more information, refer to K34150231: Exclusionary language in F5 products and documentation. | | +| Wi-Fi vs. wifi vs. WiFi | Use Wi-Fi | | +| wide IP | Use an article when describing: the wide IP or a wide IP, as appropriate). | | +| window | Do not use window or screen. Use page. | | +| Window's | NEVER say Window's (as a possessive). Just Windows. | | +| wish, desire | Do not use. Belongs in fairy tales. Use want, need, require, or prefer. | | +| Wizard and wizard | When documenting the GUI, you can capitalize Wizard if appropriate, such as for the Network Access Setup Wizard. When writing about wizards in general, or when a page title of a dialog box or GUI does not show Wizard in uppercase format, you can leave wizard in lowercase format. | | +| WWW or www | Do not include www. in web addresses In text, do not use WWW, but use Internet instead. Of course, you can use www as part of a URL. Although we're moving away from that, too. | | + +--- + +## Topic types and templates + +When writing new documentation, use the following [templates](/templates): + +- Concept Article +- Getting Started Guide +- How To Guide +- Installation Guide +- Reference Article +- Troubleshooting +- Tutorial + +## Guidelines for screenshots + +Only use screenshots when absolutely necessary, as they can be hard to keep up-to-date. Minimize their use to avoid frequent updates. Screenshots can quickly become outdated with changes in user interfaces or software versions, leading to user confusion. Consider if clear, concise written instructions can convey the information instead of a screenshot. + +If you decide to include a screenshot, follow these guidelines: + +- Use PNG format. +- Use filenames with lowercase words separated by dashes. For example, `nginx-management-suite-dashboard.png`. For consistency, don't use spaces or underscores. +- Use a resolution of 72 dpi. +- Set the width to 800 pixels for full-width screenshots. +- Use a transparent background to support both light and dark modes. +- Don't add a border; CSS automatically includes it when the screenshot is placed in the documentation. +- Don't capture the cursor in the screenshot. +- Ensure the screenshot includes the relevant item (button, menu item, icon) with enough context to locate it in the user interface and understand the action. +- Avoid unnecessary whitespace. Crop the image to include only relevant content. If needed, use image editing software to move content closer together, or ask the writers team for help. +- Use simple arrows and rectangles to highlight important items. Use a high-contrast color to make the annotations stand out. +- Include a description (`<img alt>` text) for the screenshot that provides a brief summary of the content and context. This description helps screen readers describe the image to visually impaired users. For example, "Area chart titled 'NGINX Active Connections' showing the number of active connections over time for the current date. The x-axis represents the time of day, and the y-axis represents the number of connections, ranging from 0 to 10,000. The chart is color-coded with different shades to indicate varying levels of connections." For examples and guidelines for effective alt text, see the BBC's useful guide [How to write text descriptions (alt text)](https://www.bbc.co.uk/gel/how-to-write-text-descriptions-alt-text). + +## Sensitive and personally identifying information + +Ensure content and screenshots are anonymized and don't contain sensitive information: + +- Replace personal information (names, email addresses, phone numbers) with generic placeholders. +- Replace sensitive data (IP addresses, passwords, domain names, SSH keys, OAuth 2 tokens, and other confidential information) with generic placeholders. + - Look for (and replace) sensitive words like `secret` + - Look for (and replace) content such as UUIDs and OAuth 2 keys (which start with `eY`) +- Limit the use of links to external (non-F5) sources. When necessary, only link to reputable sources and foundational sites, such as GitHub.com, Google.com, and Microsoft.com. + - This helps minimize the risk of prompt injection. + +## Guidelines for `includes` + +In an ideal world, we'd "write once, publish everywhere." It's possible with a concept known as `includes`, where an entry such as: + +``` +{{< include "controller/helper-script-prereqs.md" >}} +``` + +automatically pulls content from the `helper-script-prereqs.md` file in the `content/includes/controller` subdirectory. + +As includes disrupt the flow when reading a markdown file, we encourage you to follow these guidelines: + +- Keep includes to a minimum +- Set up includes in "small snippets" +- Use includes on content that _rarely_ changes +- Create includes for content that's repeated at least three times +- Don’t add headers (like H2s) inside includes. Headers in includes don’t show up in the in-doc TOC. Plus, while an H2 might make sense in the include on its own, it may not fit well under an H4 in the main document. Headers should be added at the doc level. +- Don’t nest includes inside other includes. While this technically works, it makes reviews harder. + +If you don't use an include with repeated content, include a `<!-- comment -->` which refers to other files with the same content. + +## Revision history + +The following table describes the history of all decisions and revisions made to +this style guide over time. This guide uses the Major.Minor.Patch +[semantic versioning](https://semver.org/) convention. + +| Edition | Date | Lead Author(s) | Comments | +|---------|---------------|----------------|-------------------------------------------------------| +| 1.5 | October 3, 2024 | Mike Jang | Include guidelines for "includes" | +| 1.4 | Septemter 20, 2024 | Mike Jang | Organize and clarify info on sensitive content | +| 1.3 | August 12, 2024 | Jon Torre | Include additional rules for product names | +| 1.2 | June 21, 2024 | Travis Martin | Added link to BBC's examples for effective alt images | +| 1.1 | May 21, 2024 | Jon Torre | Added guidelines for screenshots | +| 1.0 | May 05, 2024 | Travis Martin | First draft of Style Guide | + diff --git a/templates/tutorial/example-tutorial.md b/templates/tutorial/example-tutorial.md new file mode 100644 index 000000000..efe609266 --- /dev/null +++ b/templates/tutorial/example-tutorial.md @@ -0,0 +1,77 @@ +# How to Make Coffee + +## Overview + +This guide teaches you how to make coffee using freshly ground beans, a burr grinder, and a filter coffee machine. It's designed for coffee lovers interested in crafting quality coffee at home. + +You should know the basics of coffee beans, water, and heating methods. By the end of this guide, you'll learn how to: + +- Measure and grind coffee beans correctly +- Measure the right amount of water +- Brew the coffee properly +- Enjoy a perfect cup of coffee + +## Background + +*Optional: Add more about coffee here, like its benefits and best times to enjoy it.* + +## What You Need + +- Fresh coffee beans +- Burr grinder (for example, Baratza Encore) +- Coffee filters +- Coffee machine (for example, Moccamaster Technivorm) +- Scale that measures in grams +- Measuring cup that measures in milliliters +- Coffee cup + +## Preparation Steps + +Before you begin, ensure that your coffee grinder and machine are clean. This will prevent old coffee flavors from mixing with your fresh brew. Also, consider storing your beans in an airtight container to keep them fresh. + +## Measure the Coffee + +1. Open the coffee bag. +2. Place a bowl on the scale and zero it. +3. Add 60 grams of coffee beans for every liter of water you plan to brew. + +## Grind the Coffee + +A proper grind is crucial for great coffee. We recommend a medium grind for balanced flavor. If your coffee tastes too bitter, try a coarser grind. If it's too sour, a finer grind may be necessary. + +1. Set the grinder to a medium setting (18 on the Baratza). +2. Grind the beans until you have the desired amount. +3. Transfer the grounds to the filter in the brew basket. + +## Measure the Water + +Use 1 liter of high-quality water for every 60 grams of coffee. If tap water quality is poor, filtered or bottled water is recommended. + +1. Fill a measuring cup to the 1-liter mark. +2. Pour the water into the coffee machine's reservoir. + +## Brew the Coffee + +Ensure your coffee maker is assembled correctly and placed on a stable, heat-resistant surface. Plug the coffee maker into a grounded outlet and turn it on. + +1. Place the carafe in position. +2. Turn on the coffee maker. +3. Wait until brewing completes. + +## Post-Brew + +Once brewing is done, turn off the coffee maker. Consider using the spent coffee grounds as compost for your garden. + +## Enjoy Your Coffee + +1. Pour the freshly brewed coffee into your cup. +2. Take a moment to enjoy the aroma. +3. Sip and enjoy. + +## Summary + +You've learned how to measure, grind, and brew coffee. This simple method ensures a delicious cup every time. + +## Next Steps + +Explore further coffee-making techniques or other beverage tutorials to enhance your skills. \ No newline at end of file diff --git a/templates/tutorial/guide-tutorial.md b/templates/tutorial/guide-tutorial.md new file mode 100644 index 000000000..2a9460d01 --- /dev/null +++ b/templates/tutorial/guide-tutorial.md @@ -0,0 +1,165 @@ +# The tutorial template + +> Thank you for downloading this template from The Good Docs Project! Before using the template, read this template guide for information about how to complete each section. Want to explore more templates? Check them out in our [templates GitLab repository](https://gitlab.com/tgdp/templates). + +The tutorial template includes: + +- Placeholder text that you can replace with your own text. This text is indicated in {curly braces}. +- Writing instructions, also in {curly braces}. + +## Why do I need tutorials? + +Tutorials are integral to helping your users become acquainted with your product. They are learning-oriented and are usually focused on teaching users a specific skill, like debugging a JavaScript application. + +Tutorials are often confused with how-to guides because they do help users achieve a specific goal. However, how-to guides assume that your users have some experience with your product or are familiar with certain concepts. They also are usually focused on helping users complete a specific task, like how to add an email account to Microsoft Outlook. + +In comparison, tutorials give your users hands-on experience with your product so that they can understand key concepts about your product in a more practical context. Hands-on learning often helps learners gain a deeper understanding of the product by helping them see how they can use a tool to accomplish a task they care about. +The table below identifies the differences between the two. + +| Tutorials | How-to | +| ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| Learning oriented | Task oriented | +| Helps beginners or expert users learn a new feature, in a practical way. | Helps an expert user accomplish a task or troubleshoot an issue. | +| Follows a carefully managed path, from the start to the end. | Aims for a successful result, and guides the user along the safest, surest way to the goal. | +| Eliminates any unexpected scenarios and provides users with a successful finish. | Alerts the user to the possibility of unexpected scenarios and provides guidance on how to deal with it. | +| Assumes that users do not have any practical knowledge and must explicitly state any tools, file configurations, conceptual details, and so on. | Assumes that users have the practical knowledge of tools, file configurations, applications, and so on. | + + + +## Helpful tips when writing your tutorial + +- Keep your tutorial focused. If needed, include links to other pieces of documentation that explain concepts or terms in more depth. Ideally, your tutorial should take 15 to 60 minutes to complete. +- Lengthy tutorials can overwhelm users. Consider condensing or removing steps or reevaluating the scope of the tutorial. +- If users will copy and paste code samples, make sure they include the following: + - Any required `import` or `using` statements + - Code comments that explain what the code does + +## About the tutorial template + +This tutorial can be used in one of two ways: +- For providing a walkthrough of a particular feature. +- Walking users through completing a small project. + +Ideally, your users have already completed a quickstart or "getting started" tutorial and have a general understanding of your product before they begin your tutorial. + +### About the "Overview" section + +The overview section is important, as it can motivate your users to begin their learning journey with your product and help set them up for success. There are three topics you should cover in this section: learning objectives, intended audience, and any prerequisite background knowledge. + +#### Learning objectives + +One of the first things users want to know when they begin a tutorial is, "What will I be able to do? What knowledge will I gain by completing this tutorial?" Well-written learning objectives can help to answer these questions. **Learning objectives*- describe the specific skills or knowledge users will be able to demonstrate after completing your tutorial. + +Before you start writing your tutorial, develop some learning objectives. After you identify *what- skills and knowledge you want users to gain from your tutorial, you can start planning out the content itself, using the learning objectives to help you decide what topics are in scope, and which ones are out of scope. + +Learning objectives usually start off with, "By the end of this tutorial, you will be able to..." and are followed by a phrase that starts with a verb like *design*, *assess*, or *develop*. If your tutorial includes more than one learning objective, consider presenting them as a bulleted list. + +Here are some examples: + +- By the end of this tutorial, you'll be able to define components in React. +- By the end of this tutorial, you'll be able to perform common tasks in Google Drive, such as viewing, editing, and saving documents. +- By the end of this tutorial, you'll be able to create a private channel in Slack. + +If you need help with creating learning objectives, consider using Arizona State University's [Learning Objectives Builder tool](https://teachonline.asu.edu/objectives-builder/). + + +#### Intended audience and background knowledge + +Before you begin writing your tutorial, you need to think about who you're writing for. The audience will influence the content you include in the tutorial. + +It's important to mention the intended audience and any prerequisite knowledge in the overview section. This information helps users determine if the content is appropriate for them. + +Here are some questions to think about as you plan your tutorial: + +- Is the tutorial intended for users looking to become more familiar with your product? Or is it for users who are already familiar with your product and are looking to build upon the skills they already have? +- Is the tutorial intended for users with a certain level of technical knowledge? What technical knowledge should they know? +- Is it for a certain demographic, like senior-level database administrators who routinely complete certain tasks? + +### About the "Background" section + +The purpose of the background section is to summarize any necessary context for your users before they start your tutorial. + +If you're writing a tutorial that's focused on learning how a particular feature works, you might describe that feature here. For example, a tutorial around using Microsoft Visio's templates to build flowcharts might start with an explanation of how flowcharts are used or what flowchart shapes represent. + +If you're writing a tutorial where you provide users with a starter project, you could describe the project hierarchy here. For example, a tutorial around building a website with HTML, CSS, and JavaScript might explain how the folders are organized, what code is provided for the user, or what they need to add. + +### About the "Before you begin" section + +This section helps readers avoid getting halfway through a tutorial and then discovering they don't have something needed to complete. You can use list prerequisites for completing the tutorial, such as operating systems, languages, package managers, or software. + +### About the "Steps" section + +The steps section is where you describe what the user needs to do to complete the tutorial. The template organizes steps in the following way: + + +1. {Write the command here. Start with a verb.} + + {Optional: Explanatory text} + + {Optional: Code sample or screenshot that helps your users complete this step} + + {Optional: Result} + + +The first element is the step itself, like "Enter a name for your new repository." When writing steps, keep these tips in mind: + +- Start with an imperative verb. For example, "connect", "set up", or "arrange." Don't use the *-ing- form of the verb because it is harder to translate. +- Express steps as a complete thought. Instead of saying, "Set up access", you might say, "Set up access to a Cloud Storage bucket." + +Next, you may choose to add some additional information about the step. Continuing with the example, you might provide some best practices for creating memorable repository names. + +Optionally, you can add a code sample or screenshot after the explanatory text, depending on the type of tutorial you're writing. Screenshots are a great way to show specific parts of the screen you are referring to in a step. + +If you're including code samples in your repository, make sure to add comments to your code to help learners understand what each part of the code does. Additionally, make sure your code samples work, as learners will copy and paste your code to use in their own projects. + +The last, and optional, element in a step, is the result. Continuing with the example, you might describe what happens after a user clicks the "Create repository" button. + +Here is an example step: + +1. Enter a name for your new repository. + + Good repository names are short and self-explanatory. Avoid repository names with three or more words. + + After you click "Create repository", GitHub creates your repository and the main page for the repository is displayed. + +If needed, you can add substeps below a primary step. Make sure to indent the substep one tab space over if you're using Markdown: + +1. Create a new pull request. + + a. Navigate to the main page of your repository. + + b. Under your repository name, click **Pull requests**. + + By default, all open pull requests are displayed. + + c. .... + +If you're including code samples in your steps, make sure they are also indented correctly: + +1. Set your Git username for your repository. + + You can change the name that is associated with your Git commits using the `git config` command. + + ```bash + git config user.name "Dakota Everson" + ``` + +#### Tips for writing steps + +Here are some more tips to follow when writing procedural steps: + +- Remember to orient your users when guiding them through each step. If they need to open a particular file or dialog to complete the task, provide that information first. +- Avoid writing procedures that are more than seven primary steps long. +- Aim for no more than four substeps in any primary step. + +### About the "Summary" section + +In the summary section, you can list the knowledge and skills your users have gained by completing your tutorial. Try to avoid repeating the learning objectives you listed in the overview section word for word. + +For example, if one of your learning objectives is "define components in React", you might specify *what- your users learned about defining components in React. Did they learn how to build different types of components? Or did they learn about all required functions needed to build a component? Think about some of the most important skills they gained and list them here. + +Listing the actual skills and knowledge your users gained can also help to motivate your users to continue using your product, or try other tutorials. + +### About the "Next Steps" section + +Use this section to include links to other tutorials, such as tutorials that allow users to learn about related features. You can also include links to relevant resources, like articles, blogs, or videos. \ No newline at end of file diff --git a/templates/tutorial/template-tutorial.md b/templates/tutorial/template-tutorial.md new file mode 100644 index 000000000..71cc8b6a5 --- /dev/null +++ b/templates/tutorial/template-tutorial.md @@ -0,0 +1,81 @@ +# Title + +> If you need more information about how to fill in this template, read the accompanying [guide](./guide-tutorial.md). + +> This template includes writing instructions and boilerplate text that you can customize, use as-is, or completely replace with your own text. This text is indicated in {curly brackets}. Make sure you replace the placeholders with your own text. + +## Overview + +In this tutorial, you'll learn how to {insert brief description of the main tutorial task}. This tutorial is intended for {audience}. It assumes you have basic knowledge of: + +- Concept 1 +- Concept 2 +- Concept 3... + +By the end of this tutorial, you'll be able to: + +- Learning objective 1 +- Learning objective 2 +- Learning objective 3... + +## Background + +{This section is optional. Feel free to use some of the text below to help you get started.} + +- {product} is a {product type} that you can use to {common use case}... +- {product} provides many of the same features as {competitors}, but with {feature}, you can... +- Using {feature} enables you to {pain point}... + +## Before you start + +{Use this section to tell users about any prerequisites needed before they start the tutorial, such as: + +- Expected prior knowledge. +- Software or hardware to obtain. +- Environments to set up and configure. +- Access codes to obtain. +} + +Before you start the tutorial, you should: + +- Prerequisite 1 +- Prerequisite 2 +- Prerequisite 3... + +## {Task name} + +To get started, {the first thing your user should do}. + +1. {Write the step here. Use a verb to start.} + + {Explanatory text} + + {Optional: Code sample or screenshot that helps your users complete this step} + + {Optional: Result} + +2. {Write the step here. Use a verb to start.} + + a. {Substep 1} + + b. {Substep 1} + +## Summary + +{Use this section to summarize what the user learned in the tutorial.} + +In this tutorial, you learned how to: + +- Summary point 1 +- Summary point 2 +- Summary point 3... + +## Next steps + +{Use this section to share links to related tutorials, videos, or other documentation}. + +Consider completing some other common tasks using {feature}: + +- Task 1 +- Task 2 +- Task 3... \ No newline at end of file