Technical Editor Project

README.md

This is a technical writing and editing project as part of your interview.

This project is designed to take less than 1.5 - 2 hours.

Read the style guide snippet which is a subset of our official engineering style guide and the guide template. Then make improvements to the sample prose so it embodies the principles in the style guide.

Instructions

• Create a git repository on GitHub, GitLab, Bitbucket, or any other git hosting service.
• Download the original terraform-getting-started.md file by clicking the "Raw" button.
• Make a git commit to your repo that contains the original text of terraform-getting-started.md as listed below.
• Edit the sample text as Markdown. Look for and fix any spelling or grammar issues.
• Edit the text for readability and compatibility with the style guide.
• Add section titles to be compatible with the guide template.
• Add additional sections and content for prerequisites and next steps.
• Add the learning objectives to the introduction.
• Commit your changes to the terraform-getting-started.md file and push to the repository as a new commit.

Submit your sample

• Send the repository link to your recruiting contact for review. It will be easiest if this is a public repository.

guide-template.md

Guide Title

Introduction goes here... (e.g. what you'll learn in this guide)

Prerequisites

Example:

• Vault version 1.2.0 or later
• Kubernetes comand-line interface (CLI)
• Minikube

Action title 1

Short description of this step.

If applicable, demonstrate the steps using CLI, API, and UI.

CLI command / API call using cURL / Web UI

CLI command

API call using cURL

Web UI

Action title 2

Short description of this step.

If applicable, demonstrate the steps using CLI, API, and UI.

CLI command / API call using cURL / Web UI

CLI command

API call using cURL

Web UI

Next steps

In this section, start with a brief summary of what you have learned in this guide re-emphasizing the business value. Then provide some guideance on the next steps to extend the user's knowledge. Briefly describe what the user will do in the next guide if the current track is sequential.

Add cross-referencing links to get more information about the feature (e.g. product doc page, webinar links, blog post, etc.).

style-guide-snippet.md

HashiCorp Engineering Writing Style

Whether it is a blog post, technical documentation, or communication with users, HashiCorp has a particular writing style we do our best to adhere to.

It is important to note that these are guidelines. There are situations where violating these rules is sensible, acceptable, or required. However, try to adhere to these guides.

Why?

Having a consistent writing style and voice is what makes the HashiCorp brand strong and vibrant. There are a few reasons for the choices of our writing style. In particular:

• Optimizing for non-native speakers - HashiCorp is a global company. We have users on at least 6 continents, many of whom do not speak English (the primary language of the company and our writings). Translation tools are not very smart, but even literal translations do not mean the same thing in different colloquialisms.

• Optimizing for 2am, half awake operators - Many HashiCorp tools are in the path of downtime. While we strive to make the best tools in the world, sometimes they fail. Having flowery sentences is not helpful when trying to get a system back online.

• Optimizing for our own time - When we write in the same style, we can spend more time focusing on the content and body of a pull request or documentation change, instead of pointing out small style inconsistencies.

• Optimizing for product transitions - A user who is familiar with the Consul documentation that chooses to adopt Vault should not feel as though they need to learn an entire new language just to read the docs. This helps our overall adoption strategy.

Guiding Principles

The majority of our principles are guided by experience and user feedback. As a high-level set of rules, we follow Orwell's 6 rules:

• Never use a metaphor, simile, or other figure of speech which you are used to seeing in print.

• Never use a long word where a short one will do.

• If it is possible to cut a word out, always cut it out.

• Never use the passive where you can use the active.

• Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.

• Break any of these rules sooner than say anything outright barbarous.

Grammatical Person: "You" for the User

Write docs in the second person, addressing the reader directly as "you".

Good: Terraform Cloud's API lets you create workspaces without a VCS connection.

Bad: Terraform Cloud's API allows one to create workspaces without a VCS connection.

Active Voice: "We" for HashiCorp

Avoid passive voice; write with the active voice as much as possible.

Active voice enforces attribution. In our documentation, the opinions and advice on offer belong to us, here at HashiCorp. Our language should never try to hedge or evade responsibility for the guidance we're providing. If HashiCorp is making a recommendation, say "we".

Good:
We recommend configuring VCS access when first setting up an organization.

Bad:
It is recommended to configure VCS access when first setting up an organization.

In cases where the actor of a sentence is a tool or system (rather than a person or company), you should still use active voice, because it's easier to understand and sometimes distinguishes between automated and operator actions.

Good:
Terraform has a provider framework to leverage this behavior.

Bad:
To hook into this behavior, a provider framework has been built into Terraform.

Good:
Next, register the service

Also good:
Next, Kubernetes will register the service.

Bad:
Next, the service will be registered.

Inclusive Language

Pronouns

If you are using the grammatical person "you" for the user you probably won't use very many pronouns in your writing. If you do find yourself using pronouns, make sure they are necessary, and if so, use the gender neutral "they/them".

Good	Bad
Once you give the developer the token they can...	Once you give the developer the token she can...

Over Simplification

Our products can be complicated. Words that indicate that processes are easy don't add meaning to your writing and can alienate users who are having a hard time or encountering bugs.

Avoid saying:

• easy, easily, simply
• just (as in "just run this command")
• obviously

terraform-getting-started.md

Getting Started with Terraform

Terraform is the most popular langauge for defining and provisioning infrastructure as code (IaC).

To install Terraform, simply visit Terraform.io and download the compressed binary application executable file deliverable for your platform, machine or environment on which you like to run code and do development.

With Terraform installed, let's dive right into it and start creating some infrastructure.

Most guys find it easiest to create a new directory on there local machine and create Terraform configuration code inside it.

$ mkdir terraform-demo
$ cd terraform-demo

Next, create a file for your Terraform configuration code.

$ touch main.tf

Paste the following lines into the file.

provider "docker" {
    host = "unix:///var/run/docker.sock"
}

resource "docker_container" "nginx" {
  image = docker_image.nginx.latest
  name  = "training"
  ports {
    internal = 80
    external = 80
  }
}

resource "docker_image" "nginx" {
  name = "nginx:latest"
}

Initialize Terraform with the init command. The Docker provider will be installed.

$ terraform init

You shoud check for any errors. If it ran successfully, provision the resource with the apply command.

$ terraform apply

The command will take up to a few minutes to run and will display a message indicating that the resource was created.

Finally, destroy the infrastructure.

$ terraform destroy

Look for a message are the bottom of the output asking for confirmation. Type yes and hit ENTER. Terraform will destroy the resources it had created earlier.