A guideline is a written statement that helps make autonomous decisions.
All guidelines are stored in this repository. You can find them either by using keyword search or navigating the categories.
You need to follow the advice process to arrive at a decision. Anyone in the advice process can initiate a consent process to create a guideline based on the advice.
Sometimes you may discover that an existing guideline does not cover your specific case, is out of sync with current best practice or contradicts other guidelines. In such case you don't have to follow it, but you need to follow the advice process to arrive at a decision. Anyone in the advice process can initiate a consent process to amend the guideline.
It's important to reflect on your motivation for proposing a new guideline. The goal with guidance is to have only that which is necessary to make the company run smoothly and well. It should not be in reaction to bad behaviour or one-off situation. Assess whether feedback or conflict resolution might be a more appropriate means of dealing with it.
Guideline creation and amendment is done through consent process (to-do: add a link to consent process here), as a result of the advice process. The person/s who propose the guideline creation / amendment are responsible for moving the process forward. Team-led guideline creation is encouraged. Even if a guideline has a scope (company, office, functional team, project team) the whole team can participate in the consent process.
- For new guidelines, make sure the guideline you are adding doesn't already exist.
- For existing ones, make sure you review the history of changes to see if the issue you propose to amend has already been discussed before.
- Perform due diligence to understand context and background around the issue (has this been discussed before, is there a de facto practice already in place, are there conflicting views about the matter?)
- Whenever possible try to keep the current high-level structure. Create new sections or subsections only when necessary.
- Keep things as simple as possible, only write new guidelines when they are needed.
- Write in clear, specific and actionable terms. Guidelines are decision helpers, not judgments or theoretical statements.
Since we're using GitHub as a guideline repository, the natural way of suggesting changes is via the mechanism of Pull Requests
The starting point is to have your content saved in a branch of the repository (please do not commit directly into master, unless maybe you see a typo). There are a few ways technically to do that, broadly speaking:
- you can clone the repo to your machine, create a branch, make changes and push like you'd do with code
- you can use GitHub's interface
When using the GitHub interface, first create a new branch by using the "Branch" dropdown, then switch to your branch. You can edit existing files (edit button when viewing a file) or create new ones ("Create new file" button), every time saving your changes by comitting them to your branch. When you're done with the changes, you can use the "Pull request" button on the "Code" tab of your branch. It's also possible to do the same starting from the "Pull requests" tab and selecting your branch.
There is also a shortcut if you only want to edit / create a single file. Start making your changes while on a branch that you want to use as your base. To save the changes on a new branch and start the pull request, in the "Commit changes" section select "Create a new branch for this commit and start a pull request".
- Start your PR with a short and meaningful title (e.g. "Guideline for hiring process").
- Briefly explain the motivation for the guideline creation/amendment and the context and background.
- The created / amended text of the guideline should also be added to the PR text for easier reading.
- Add as assignees the people who are leading this guideline creation, including yourself.
- Add as reviewers the people who should be involved by giving advice, or who are directly affected. Remember that anyone can participate.
- Announce the new guideline creation / amendment process on #general channel in Slack.
- Allow up to 3 days for comments.
- Announce the outcome on #general channel in Slack.
- Please follow the Consent process. In that process a decision does not require everybody to agree, it only requires that nobody raises a meaningful objection.
- Use the reactions 👍 "Agree", 😕 "Disagree", 👎 "Object" and explain clearly afterward your reasons.
- Use the keyword "Proposed changes" to suggest amendments, corrections or additions.
- If you want to propose a bigger change, edit the file directly and include a link to the diff in the comment box. You can also paste the new wording in the comment box.
- If you were assigned as a reviewer of a pull request, you have additional tools available to comment on particular sections of the text, approve or request changes.
- Try not to make judgments. Base your opinions on facts or rational reasons rather than judgments or emotions.
- Use Non-Violent Communication.
- Provide your comments in a timely manner, normally up to 3 days.
This is where you can access the content of this repository as a web page: https://vizzuality.github.io/playbook/
You can use the editor on GitHub to maintain and preview the content for your website in Markdown files.
Whenever you commit to this repository, GitHub Pages will run Jekyll to rebuild the pages in your site, from the content in your Markdown files.
Markdown is a lightweight and easy-to-use syntax for styling your writing. It includes conventions for
Syntax highlighted code block
# Header 1
## Header 2
### Header 3
- Bulleted
- List
1. Numbered
2. List
**Bold** and _Italic_ and `Code` text
[Link](url) and For more details see GitHub Flavored Markdown.
Your Pages site will use the layout and styles from the Jekyll theme you have selected in your repository settings. The name of this theme is saved in the Jekyll _config.yml configuration file.
Having trouble with Pages? Check out our documentation or contact support and we’ll help you sort it out.
=======