Create README.md

docs/about-this-guidebook/README.md

@@ -0,0 +1,21 @@
+# How and when to contribute to the guidebook
+
+This guidebook is written by and for all employees of CivicActions. Everyone is encouraged to contribute to continuously improve it.
+
+The most common incentive to create or edit documentation is to "scratch an itch" that's felt when we come across a lack of information, or lack of standards around a practice. If you find a hole in the documentation, you're probably the best person to take a stab at filling it.
+
+We also have [a Trello board](https://trello.com/b/ZKx6l4bC/civicactions-documentation-project) to manage the documentation backlog. Feel free to pick something off the backlog to work on.
+
+We also use the [#docs](https://civicactions.slack.com/messages/docs/) channel in Slack to communicate.
+
+## Minimal Viable Contribution
+
+Better than doing nothing at all:
+
+- [Open a Trello card](https://trello.com/b/ZKx6l4bC/civicactions-documentation-project) with a documentation suggestion, or
+- Create an [issue in GitHub](https://github.com/CivicActions/handbook/issues/new).
+- Chat about it in [#docs](https://civicactions.slack.com/messages/docs/).
+
+## Writing documentation
+
+You should read the rest of this section if you intend to contribute beyond a Trello ticket, issue, or chatting in the #docs channel.

docs/about-this-guidebook/file-structure.md

@@ -0,0 +1,7 @@
+# Guidebook file structure
+
+The only files in the root directory of the repo (above docs/) are configuration files and the main repo README.md, which is what you find at <https://github.com/CivicActions/handbook>.
+
+Within the docs folder, the folder and file structure is based on internal research on business and employee needs.
+
+Folders and file names should all be lowercase and avoid special characters, except for hyphens (in place of spaces).

docs/about-this-guidebook/git-workflow.md

@@ -0,0 +1,90 @@
+# Git workflow
+
+Git is a powerful version control tool that you can learn. At its core is the idea of cloning code, making changes, and merging those changes back in. In our case, those changes get merged back in after a "pull request" containing those changes gets made, reviewed, and accepted.
+
+Git is confusing at first, but our handbook is a great place to learn Git because we use a relatively simple Git workflow, compared to many engineering projects.
+
+In this project, The "master" branch is the active branch, with the latest, approved changes, published at [Read The Docs](https://handbook.civicactions.com/en/latest/README/). If you use Workflow 1, you'll be editing the branch directly, but
+
+## The easy way, via the GitHub UI on the master branch
+
+We recommend this approach for those who are not already familiar with the Git workflow, and who do not have tools for keeping their GitHub forks up to date.
+
+You'll need a GitHub account, and to be added to the CivicActions Team ([using these instructions](../050-how-we-work/tools/github.md)).
+
+Go to a page, click edit, and make your changes, using [markdown](markdown-for-guidebook.md). Before you commit your changes, click the "Preview changes" tab to make sure your formatting is good and everything looks right.
+
+When you save it ("make a commit"), there are three fields to fill out. _All of these are optional_, with default values, and in most cases it's fine to leave the defaults.
+
+- **The commit title**: By default it is something like "Update \[filename]". You can usually leave this as is (often this is ideal), or you can be more precise, but keep it short.
+- **Extended description**: Explain your changes, if you wish. Useful if you need more than the 50 characters available in the title.
+- **The branch name:** By default this will be a new branch, with a name like \[username]-patch-1. If you want to change it to something more semantic (eg \[username]-easy-github-contributing), that can be helpful to the reviewers, but it's not necessary.
+
+After you commit, you will be asked if you want to create a new pull request with the branch you created. You'll again be presented with a few fields, which you can generally leave as is.
+
+- **The PR title:** By default it is the title of your last commit.
+- **Extended description:** This also draws from your last commit.
+- **The right sidebar:** You can assign your pull request to someone on the team (someone you think may want to review your edits).
+
+Most of the time you don't need to fill anything out, just click "Create pull request".
+
+Or, if you want to make other changes on the same branch and have it reviewed at the same time as the commit you just made, don't create the PR quite yet. Navigate to the branch you created in your first commit (eg <https://github.com/CivicActions/handbook/tree/[your-branch-name]>. You can also find this branch from the handbook homepage by clicking on [branches](https://github.com/CivicActions/handbook/branches). Then, edit another file (or the same file you just edited) and commit it. This time, GitHub will know that you want to commit to the same branch as you created during your first commit.
+
+Once you are done making commits to your branch, you can then create a PR from your branch to the master branch, which will include all changes.
+
+## The more advanced way: fork the handbook
+
+**NB: Currently, pull requests submitted from forks of the handbook will not properly interact with the GitLab CI pipeline and will fail their automated tests. Until further notice, the preferred contribution method is to create a branch in the CivicActions/handbook repository and submit a PR from there.**
+
+If you're familiar with the Git fork and pull request (PR) workflow, we definitely recommend forking this repo and making pull requests from your fork. This is the recommended way to contribute.
+
+The easiest way to get started, if you're not familiar with the command line or an existing git repo management tool, is by installing [GitHub Desktop](https://desktop.github.com/), and then learning how to keep your fork up to date with the latest, create commits, and submit PRs.
+
+You can use any other number of tools, including text editors (such as [Atom](https://atom.io/)) and the command line, or other GUI tools.
+
+Resources:
+
+- [Fork a Repo](https://help.github.com/articles/fork-a-repo/)
+- [Working with Forks](https://help.github.com/articles/working-with-forks/)
+- [Getting Started with GitHub Desktop](https://help.github.com/en/desktop/getting-started-with-github-desktop)
+- [Contributing to Projects with GitHub Desktop](https://help.github.com/desktop/guides/contributing/)
+
+## Assignment of pull requests
+
+Your PR will automatically be assigned to a team for a review, based on which part of the handbook you are editing. That automatic review assignment is explained in [Guidebook governance](guidebook-governance.md). If you think that certain individuals on the team may have particular subject matter expertise or authority on the topic, you can also assign them directly via the "Reviewers" section of the right hand sidebar.
+
+## How to review and merge pull requests
+
+Each pull request must be reviewed by at least one other CivicActions employee before it can be merged.
+
+Any CivicActions employee with GitHub account, who has been added to the CivicActions Team ([instructions are here](../050-how-we-work/tools/github.md)), can review a pull request and decide whether they feel confident about merging it. If it's not your area of expertise, ask somebody at CivicActions who has expertise in that area.
+
+For example: if something looks like it's related to how Marketing works, ask a Marketing person to review it; if it looks like it needs Project Management team review, ask a PM.
+
+If you're not sure if you should merge something, ask for a second opinion in [#docs](https://civicactions.slack.com/messages/docs/) first.
+
+### Step-by-step instructions for reviewing, approving, and merging PRs:
+
+1. Navigate to the open pull request. You can get there by clicking on the PR link if you have it, or by clicking on the Pull Requests tab at the top of the Handbook repo page.
+
+![PR workflow screenshot 1](../images/01-PR-pull-requests-tab.png)
+
+2. Check to make sure "All checks have passed." If not, ask the person who added the PR to fix any errors.
+
+![PR workflow screenshot 2](../images/02-PR-checks-passed.png)
+
+3. Click "Add your review."
+
+![PR workflow screenshot 3](../images/03-PR-add-review.png)
+
+4. Review the commits. If the changes look good, make sure you select "Approve." Otherwise, add your comments or request changes (merging on the PR will be blocked until you or another reviewer approves it).
+
+![PR workflow screenshot 4](../images/04-PR-approve.png)
+
+5. Submit your review.
+
+![PR workflow screenshot 5](../images/05-PR-submit-review.png)
+
+6. Merge Pull Request, and you're done!
+
+![PR workflow screenshot 6](../images/06-PR-merge.png)

docs/about-this-guidebook/github-actions.md

@@ -0,0 +1,13 @@
+# GitHub actions
+
+GitHub Actions CI is a hosted, distributed continuous integration service used to build and test projects hosted at GitHub. Actions automatically detects when a commit has been made and pushed to a GitHub repository, and each time this happens, it will try to build the project and run tests.
+
+Every time a pull request is made to the handbook repo, or when a commit is merged, GitHub CI will run tests to ensure that commit complies with certain standards. For now, it is primarily concerned with our [markdown](markdown-for-guidebook.md) syntax, and will "fail" if there are errors as specified in the .remarkrc.error file in the root directory of this repo.
+
+## What to do if your a build fails
+
+Each time a commit or PR is made to the master repo, the tests will run, and a report is created with the results of that test. A bot posts a link to the report on the merge request page in GitHub, as well as in the #docs channel in Slack. If it fails, you can click the report number and see what went wrong.
+
+The left hand column shows the line and the position in that line where the error/warning occurs, and explains which test failed, which should provide you with enough information about how to address it.
+
+You can see some recent runs at <https://github.com/CivicActions/handbook/actions>.

docs/about-this-guidebook/guidebook-governance.md

@@ -0,0 +1,37 @@
+# Guidebook governance
+
+Every team member with a GitHub account is empowered to make [pull requests](git-workflow.md) to change any part of the documentation, and every team member is encouraged to review any pull request.
+
+Ideally, pull requests should be assigned to team members who are subject matter experts. For example, changes to the LICENSE.md file were assigned to a lawyer (who happens to be a copyleft and FLOSS expert). If you're not sure who to assign the PR too, you might want to ask in the #docs channel.
+
+## Governance driven by practice area and working groups.
+
+We encourage each team at CivicActions (aka Working Group, Practice Area, Guild, etc.) to take ownership over their respective documentation. To that end, changes to files in certain directories require at least one review and approval from a member of the respective team, and members of those teams will be notified of that PR. For example, changes to the [060-engineering](../060-engineering) directory requires at least one review and approval from a member of the [Engineering Team](https://github.com/orgs/CivicActions/teams/engineering/members).
+
+These teams are listed on GitHub as [subteams](https://github.com/orgs/CivicActions/teams/civicactions-team/teams) of the main [CivicActions team](https://github.com/orgs/CivicActions/teams/civicactions-team). If you want to join one of those teams, you can go to the team page and "Request to join". A maintainer of that team will receive a notification and can approve you. You can see the maintainers from the team page, feel free to bug them for an approval.
+
+| **Directory in `docs/`**                                        | **Subteam (Working group / Practice Area)**                                    |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| [`000-contributing`](../000-contributing/)                      | [Docs](https://github.com/orgs/CivicActions/teams/docs/members)                |
+| [`010-welcome-to-civicactions`](../010-welcome-to-civicactions) | [Anyone](https://github.com/orgs/CivicActions/teams/civicactions-team/members) |
+| [`020-about-us`](../020-about-us)                               | [Anyone](https://github.com/orgs/CivicActions/teams/civicactions-team/members) |
+| [`030-policies`](../030-policies)                               | [Management](https://github.com/orgs/CivicActions/teams/management/members)    |
+| [`040-employee-handbook-us`](../040-employee-handbook-us)       | [Legal](https://github.com/orgs/CivicActions/teams/legal/members)              |
+| [`050-how-we-work`](../050-how-we-work)                         | [Anyone](https://github.com/orgs/CivicActions/teams/civicactions-team/members) |
+| [`060-engineering`](../060-engineering)                         | [Engineering](https://github.com/orgs/CivicActions/teams/engineering/members)  |
+| [`070-project-management`](../070-project-management)           | [Project Managers](https://github.com/orgs/CivicActions/teams/pm/members)      |
+| [`080-sales-and-marketing`](../080-sales-and-marketing)         | [Anyone](https://github.com/orgs/CivicActions/teams/civicactions-team/members) |
+| [`090-peopleops`](../090-peopleops)                             | [Management](https://github.com/orgs/CivicActions/teams/management/members)    |
+| [`100-security`](../100-security)                               | [Security](https://github.com/orgs/CivicActions/teams/security/members)        |
+
+Ideally, each of the above working groups have their own backlog of documentation tasks, and make documentation a regular part of their workflow.
+
+> @todo or will we use GitHub issues, with issue tags for each team?
+
+The [CODEOWNERS](https://github.com/civicactions/handbook/blob/master/CODEOWNERS) file in the top level of this repo maps the governance of `docs/` directories to their respective GitHub teams and CivicActions practice areas, and automatically assigns pull requests to that team for review, when a PR is submitted that.
+
+## GitHub team management
+
+GitHub team management is an ongoing responsibility of the Docs working group, but is generally [taken care of during onboarding](https://trello.com/c/I5L6gPiQ/174-add-to-github).
+
+To add someone to a team, go to the [subteam page](https://github.com/orgs/CivicActions/teams/civicactions-team/teams) and click _Add a member_.

docs/about-this-guidebook/guidebook-writing-style.md

@@ -0,0 +1,23 @@
+# Guidebook writing style
+
+## Tone
+
+This will be fleshed out in future iterations. For now, keep in mind that content appearing in the handbook should be welcoming, personable, and free from jargon.
+
+## How to capitalize titles and headings
+
+We use sentence case for our titles and headings. When using sentence case, we capitalize the first word, all proper nouns, and a word following a colon. We do not capitalize the next word if a title or heading begins with a number.
+
+Examples
+
+- Site building using Drupal
+- Engineer's role in client relationships
+- Accessibility: Everyone has a role
+
+## Suggestions
+
+The [GitHub Actions build](github-actions.md) outputs a list of suggestions to improve the readability, language, and grammar of the file(s) your pull requests touches. You are encouraged to review and incorporate these.
+
+## Specific terms
+
+- Never refer to "Open Source" Software without specifying it Free/Libre Open Source Software, which can be shortened to FLOSS. See [Richard Stallman's explanation](https://www.gnu.org/philosophy/floss-and-foss.en.html) if you want to know more.

docs/about-this-guidebook/markdown-for-guidebook.md

@@ -0,0 +1,57 @@
+# Markdown for this guidebook
+
+The documentation is written in markdown.
+
+## The Commonmark spec
+
+Markdown has always been a pretty loose-goosey syntax, but because our documentation is published at Readthedocs, we've adopted the [Commonmark](http://commonmark.org/) spec, which is somewhat more strict than the markdown parsers you may be used to using in various web apps like Jira, or Trello. For this reason, it's probably worth upping your Markdown game, even if you've been using it for years. The linter (more on that below) will complain if you use the wrong syntax, and your edits will not be merge-able.
+
+There's a great tutorial [on the Commonmark website](http://commonmark.org/help/tutorial/).
+
+## Common markdown errors to avoid
+
+- You need a blank line before every "block" of text. "Blocks" include paragraphs, headings, lists, code blocks, blockquotes, etc.
+- You need a blank line at the end of each file.
+- Headings (#, ##, ###, etc.) must increment correctly. You can't go from # (h1) to ### (h3).
+
+## Format auto-correct
+
+- Many common Markdown formatting issues will be automatically corrected after you submit your Pull Request by the FOSS [Restyler](https://restyled.io/).
+- This applies the FOSS tool [Prettier](https://prettier.io/) using the default configuration, which is our canonical standard.
+
+## Markdown linter
+
+We are using <http://remark.js.org/> for additional linting/checking our markdown syntax as well as making suggestions around common readability, language and grammar issues.
+
+- The [remarkrc.problem file](https://github.com/CivicActions/handbook/blob/master/lint/config/remarkrc.problem) shows a list of all the rules being enforced.
+- The [remarkrc.suggestion file](https://github.com/CivicActions/handbook/blob/master/lint/config/remarkrc.suggestion) shows a list of all rules used to give suggestions.
+
+This linter is run by [GitHub Actions](github-actions.md) with each pull request and code merge, and will automatically post a pull request review indicating problems and suggestions. You can also access the log of problems and suggestions from the GitHub Actions check details link.
+
+Finally, the mkdocs command (which is what Readthedocs) uses to build the web version of the documentation is run - this may identify broken links or other issues in your pull request.
+
+### Running the linter and format auto-correct locally
+
+You can check that your markdown complies with the retext and remark locally:
+
+- Install node.js if you don't have it already: <https://nodejs.org/en/download/> (or use a package manager).
+- Install yarn: <https://yarnpkg.com/lang/en/docs/install/> (various options to install, could also use a package manager).
+- Open a terminal and `cd` to your Git root.
+- Run `yarn install` to install the dependencies.
+- Run `./node_modules/.bin/gulp` (you can also pass in `--path=` to a specific file to limit tests to just that).
+- Run `./node_modules/.bin/prettier --write <path>` to automatically format a file.
+
+## Editors
+
+Markdown can be really easy to use with a good editor such as some of these [text editors](../050-how-we-work/tools/text-editors.md) - many editors have plugins that support Prettier and Remark linting for real time fixing and feedback on your edits.
+
+## Mixing HTML and Markdown
+
+For any markup that is not covered by Markdown's syntax, you simply use HTML itself. There's no need to preface it or delimit it to indicate that you're switching from Markdown to HTML; you just use the tags.
+
+Examples:
+
+<details>
+  <summary>Example of an accordion</summary>
+  HTML block
+</details>