lone-writers-guide

Contents

• About this guide
• How to participate
• How to edit in the browser
• How to fork this repo and work offline, in your favorite text editor

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

About This Guide

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.

How to participate

You can contribute in several ways:

• Edit these pages in your browser
• Fork or clone the repo and work offline
• Open an issue in GitHub. This allows you to report a bug or make a suggestion without having to make the changes yourself. The GitHub documentation explains how to open an issue.

Edit in the Browser

Before you edit this repo on your browser:

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

Then follow these steps:

1. Fork the Repo (Click the Fork button in the upper right hand corner. Now you have a copy of the repo in your collection.) If you need more help, use the GitHub docs: https://help.github.com/articles/fork-a-repo/

2. Edit the docs

   • Navigate to your GitHub profile; then go to your repos; then open the repo that you just forked (copied).
   • Find a page you want to change, and push the edit button in the upper right.
   • Here's a handy guide to using reStructuredText: http://www.sphinx-doc.org/en/master/rest.html (But some documents are already formatted, so you may be able to figure out how to do headings, bullets, etc.)
   • 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

   a. 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.)

   b. Click the blue link that says Compare Across Forks.

   c. 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.

   d. Remember to push the green button that says Create Pull Request.

You're done.

After submitting changes, remember to watch 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.

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.

After you edit or create pages, you can submit the changes by completing a pull request.

To Fork and Clone the repo follow with this tutorial: https://github.com/cwcromwell/docs/blob/master/GitTutorial.md