The Lone Writer’s Guide

The Lone Writer's Guide is one of the projects happening at San Francisco Write The docs.

• Introduction
• Current Status
• Contents
• Contributing

Introduction

If you're the new sole writer at a company and you've inherited a mess, what should you do first? What decisions (and trade-offs) must you address right away? What milestones should you hit in the first 30, 60, and 90 days?

We started a guide for people who are thrown into the deep end to give them a plan for the first 90 days. This hack-a-thon is to continue that work.

Everyone has something to share, so join us for this project if you are (or have been) the sole writer at a company or a writer with lots of experience.

Current Status

This guide is in active development and has not yet been published.

Contents

We’re still working out how we want to organize what we’ve got so far, so this is very much a work in progress (WIP). If you see a better way to organize our contents, please open an issue or a Pull Request!

• Audit Existing Content
• Authoring Tools
• Authoring Tools Changing
• Content Review Procedures
• Create a Style Guide
• Create Technical Glossary
• Doc Team Procedures
• Expectations
• Getting Everyone To Write
• Identify Your Audiences
• Identify Your SMEs
• Identify Your Stakeholders
• Inheriting A Mess
• Quick Wins
• Resources
• Static Site Generators
• Technical Product Summary
• Testing Docs
• Topic Patterns
• Working With Your Manager

Contributing

You can contribute in several ways:

• You can edit these pages in your browser
• If you feel like a challenge, you can also Fork or clone the repo and work offline, but it's not necessary. There are some helpful instructions below, if you want to try that.
• Open an issue here in GitHub. This allows you to report a bug or make a suggestion without having to make the changes yourself. See the GitHub docs: Creating an Issue.

Before Contributing

Before you contribute, please:

• Review the docs to get an idea of what has been done so far
• If you already have a GitHub account, log in. Otherwise, sign up.

Edit in Your Browser the Easy Way

1. Use the edit button to start.
   1. It's the one at the upper right with a symbol that looks like a pencil.
2. When finished, scroll down to click Commit Changes.
3. Click Create Pull Request.

Edit in Your Browser the Slightly Harder Way -- by Forking the Repo

1. Fork the Repo
   1. Click the Fork button in the upper right hand corner.
   2. Now you have a copy of the repo in your GitHub account.
   3. If you need more help, see Fork a Repo.
2. Edit the docs
   1. Navigate to your GitHub profile; then go to your repos; then open the repo that you just forked (copied)
   2. Find a page you want to change, and push the edit button in the upper right.
   3. Here's a handy guide to using reStructuredText (But some documents are already formatted, so you may be able to figure out how to do headings, bullets, etc.)
   4. When you finish working on a page, scroll to the bottom of the page and push the Commit button.
3. Submit your changes through a pull request
   1. Go to the original repo (the repo you forked from, not your forked copy), and push the button that says New Pull Request. (It's only on the main page.)
   2. Click the blue link that says Compare Across Forks.
   3. Use the third pulldown window from the left to choose the name of your forked repo. You should see the comment you saved when you made the commit. And if you scroll down, you should be able to see a diff of the changes to the document.
   4. Remember to push the green button that says Create Pull Request.

And you're done!

After submitting changes, keep an eye on the pull request. Check back in a day or two to see whether the owner of the repo needs you to answer questions or make changes before your suggestions are merged into the project.

How To Edit in Your Favorite Text Editor

To edit in your text editor (as opposed to the browser) you need to fork and clone the repo. This is the pattern you should learn if you want to work on open-source documentation.

Forking means you make your own copy of the repo so you can make all the changes you want without disturbing the main project.

Cloning the repo means that you download a copy to your own computer, so you can work on it offline.

To Fork and Clone the repo follow this tutorial.

After you edit or create pages, you can submit the changes by completing a Pull Request, which is also explained in the tutorial.