Skip to content
This repository has been archived by the owner on Sep 24, 2022. It is now read-only.

Commit

Permalink
Updated review comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@gayathri-krishnaswamy
gayathri-krishnaswamy committed Jan 27, 2022
1 parent 46bd8a9 commit fc96bda
Show file tree
Hide file tree
Showing 2 changed files with 60 additions and 62 deletions.
106 changes: 57 additions & 49 deletions quickstarts/quickstart-template-guide.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Quickstart Guide

:information_source: Read this document before you start working on the [quickstart template](template-quickstarts.md)
:information_source: Read this document before you start working on the [quickstart template](quickstart-template.md).

## Introduction

Expand All @@ -10,50 +10,48 @@ It focuses on the **primary feature** of the application and helps your users to
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?
- 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 do I install and configure the application?
- How can I get any required access keys or authentication credentials?
- Hello World:
- How can I run a simple workflow for a core feature or a common use? case.
- 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 a 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?
- What other features are available to explore in the application?

A Quickstart guide is often confused with a Getting Started guide. Though both these documents help the users get acquainted with the application they widely differ in their target audience.

There are instances where a Marketing guide is often confused with a Quickstart and a Getting Started guide. The inline table gives a brief comparison about the differences.
Quickstart 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 about the differences:

| |Quickstart Guide|Getting Started Guide| Marketing Guide|
|--------|----------------|----------------------|---------------|
|Target Audience|Domain Experts: Know the problem space and are aware of what they need to do|Beginners:New to problem space and the product|Business Decision Maker: Makes strategic decisions on whether to buy the product
|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 quickstart?

A quickstart is often the first opportunity for your user to build an opinion about the technical quality of your project. It can:
A quickstart is often the first opportunity for your users to form a positive impression on your product, and build an opinion on the technology it was built on. It can:
- Make users comfortable using the application.
- Work with any application version the user might use.
- Lead to the willingness to handle complex workflows.
- Help the users in exploring additional features.
- Improve the customer experience, and help reduce costs by lowering the number of support requests.

## Tips for writing a quickstart

- Highlight the primary feature of your application.
- Document the quickest/easiest way to implement the primary feature of your application.
- Pick a use case that the user can complete within 1-2 hours with a preference for a shorter time.
- 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 quickstart
Before you start working on your quickstart, identify:
- Primary feature of your application.
- Quickest and the easiest way to implement end-to-end the primary feature of your application.
- Use case that your user can complete within 1 - 2 hours with a preference for a shorter time.
- Audience as it helps the users determine if the quickstart is relevant for their usage.

## Best practices for writing a quickstart
- Avoid complicating the quickstart by including error scenarios/complex use cases.
- Lengthy quickstarts can overwhelm users. Consider condensing or removing steps or reevaluating the scope of the quickstart.
- Remove the burden of setup requirements as much as possible through sandbox accounts.
- Ensure that the quickstart actually 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 "Metadata" fields

For more information on how to update the metadata, see [Document version](../base/base-guide.md#document-version), [Last Updated](../base/base-guide.md#last-updated), and [Application Version](../base/base-guide.md#application-versions) on the Good Docs Projects Base template.
- Any required `import` or `using` statements.
- Code comments that explain what the code does.

## About the "Overview" section

Expand All @@ -64,68 +62,78 @@ Use this section to provide the following:
- The intended audience for this document.
- The basic knowledge that you expect the user to have before using this quickstart.

Defining the audience right in the beginning helps the users identify if the quickstart is relevant for their usage.

## 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 quickstart.
For easy understanding, we recommend that you classify the prerequisites into different categories such as software prerequisites, hardware prerequisites, and so on.


For easy understanding, consider classifying the prerequisites into different categories such as software prerequisites, hardware prerequisites, and so on.

## About the "Installation" section
## About the "Install" section

This section is optional.

:memo: Not all quickstart guides requires installation section. Include this section if:
- Installation and/or configuration is done at the same time, and by the same person running the quickstart.
:memo: Not all quickstart 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 quickstart.
- Installation of a specific software(s) are a prerequisite to running the quickstart.

The purpose of this section is to provide instructions to your users on how to install/configure a particular software/tool before running the quickstart.
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 quickstart.

:memo: This section may not be relevant for Cloud/API-based applications where authorization/authentication information is more applicable.
: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/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 applicable.
- 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 install 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 quickstart into **parts**. One part of the quickstart may focus on completing several related steps. You're welcome to follow this structure or use the step headings on their own.
This template breaks down the quickstart into parts. One part of the quickstart may focus on completing several related steps. You're welcome to follow this structure or use the step headings on their own.

If your quickstart 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 quickstart guide to onboard an app as follows:

If your quickstart involves many complex tasks then break it down into different logical parts with each part consisting of one or more related steps. For example, structure a quickstart 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 quickstart does not involve many independent tasks, we recommend that you add only the logical steps. For example, structure a quickstart guide to create a new project in Visual Studio as follows:
However, if your quickstart does not involve many independent tasks, only add the logical steps. For example, you can structure a quickstart 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 quickstart

- Number the steps in the format {part}.{step} as it helps your users to easily identify and locate procedures in the quickstart. Also, this helps in referencing a particular step in a lengthy quickstart.
- Start the heading with a verb and express the step/part headings as a complete thought. 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.
- Start the heading with a verb and express the step/part headings as a complete thought. For example, you could use the heading **Connect to the VM instance** instead of **Connect**. Don't use the *-ing* form of the verb because it is harder to translate.
- 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 differents 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.
- Use plain language and define the terminology of any technical term next to it.
- 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**.
Expand Down
16 changes: 3 additions & 13 deletions quickstarts/quickstart-template.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,7 @@

# Title

:information_source: Before using this template, read the accompanying [quickstart template guide](about-quickstarts.md).

**Document Version:** {MAJOR.MINOR.PATCH}

**Last Updated:** {"Month DD, YYYY" or "Month YYYY"}

**Application Version:**

- {Application 1}: {MAJOR.MINOR.PATCH}
- {Application 2}: {MAJOR.MINOR.PATCH} or later
- ...
:information_source: Before using this template, read the accompanying [quickstart template guide](quickstart-template-guide.md).

## Overview

Expand All @@ -21,7 +11,7 @@ This quickstart guides you through:
- [Part 2](#part-2-taskname)
- [Part n](#part-n-taskname)

:information_source: (Optional) Link each part to its corresponding section for easy access
: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
Expand All @@ -34,7 +24,7 @@ It is intended for {audience}. It assumes that you have basic knowledge of:

:information_source: This section is optional.

Complete all prerequisites before proceeding with the rest of the quickstart
Before running this quickstart, you {should / will need to} have completed the following prerequisites:

- Prerequisite 1
- Prerequisite 2
Expand Down

0 comments on commit fc96bda

Please sign in to comment.