A Practical Guide for Evolving Agile and Resilient Organizations with Sociocracy 3.0

This repository contains the source files for the book A Practical Guide for Evolving Agile and Resilient Organizations with Sociocracy 3.0, currently available as

• fast and mobile-friendly static html pages: http://patterns.sociocracy30.org
• ePub and PDF

German, Hebrew and French versions also exist and are also available via sociocracy30.org/guide/. If you want to help with translations into your language, please take a look at the translations page.

Contribution Guidelines

This repository serves several main purposes:

• as a means of making all content available to people who want to build on it in simple and open file formats
• as a means of deploying the practical guide in its various forms
• as a means of making the text easily accessible for translations
• as a means of making changes to the practical guide transparent

The actual content of the practical guide is being developed outside of this repository by Lili David, James Priest and Bernhard Bockelbrink.

If you want to contribute towards the improvement of the Practical Guide, we have set up [a dedicated page](https://sociocracy30.org/ways-of-contributing-to-the-development-of-s3/ that explains how to notify us about typos and corrections, how to raise technical issues and how to suggest more significant updates to the content).

Please note that we can't promise picking up github issues on a regular basis, and due to the nature of our development process, and we can't guarantee that we will accept any pull requests that include changes to the content of the Practical Guide.

Project Structure

• content: all the files that are uploaded to Crowdin for translation (or downloaded from crowdin to the translated repositories)
• global: files that are identical across languages, mostly templates, including some with translatable content that is collected in content/translations.pot, because Crowdin does not play nice with these files. Also contains not language-specific configuration file
• config: language-specific configuration files: project.yaml, make-conf, LaTEX styles etc
• release: the latest releasable builds (must be copied there manually, all build scripts deliver their output to the project root)
• tmp the Temporary folder is autogenerated by build.sh or with make setup

Build Process

build.sh builds all available targets, you can also use make <target> to build individual target.

The build process relies on mdtools to prepare and compile the individual files, and on Pandoc for ePub and LaTEX for PDF.

Before the first target can be built, you need to run make setup, and the before building the static site adding or removing source files or illustrations it's a good idea to run make clean.

To set up a new language, run make clean and then copy over content, global, config and all files in the project root except for crowdin.yaml and upload-translations.sh. Adapt build.sh so it only contains targets that are available in that language (e.g. deckset makes no sense for RTL languages).

Known Issues

The ePub will benefit from polishing the stylesheet and setting some metadata for iBooks.

Markdown Styleguide

Information in this section is preliminary, and needs further testing.

The Markdown files for the individual patterns are grouped in directories per patterns group and built using a build script.

The following rules apply:

• MMd-transclusion via {{filename}} is possible for all templates rendered via MMD
• Markdown must conform to GitHub-flavored Markdown so that the Jekyll-version is feature complete

Translations

The content is translated in a dedicated crowdin project. The repository contains crowdin.yaml for use with the crowdin CLI.

Uploading sources is handled through this command (remove --dryrun to run):

crowdin --identity ~/crowdin-s3-patterns.yaml --dryrun upload sources

For each major revision we will create a branch with the version tag in crowdin, so future updates do not disrupt translation efforts:

crowdin --identity ~/crowdin-s3-patterns.yaml upload sources -b {branch name} --dryrun

The config file can be checked using crowdin --identity ~/crowdin-s3-patterns.yaml lint

These commands assume crowdin credentials in ~/crowdin-s3-patterns.yaml

License

This book is created by Bernhard Bockelbrink, James Priest and Liliana David, using illustrations from the S3-Illustrations Repository by Bernhard Bockelbrink.

A Practical Guide for Evolving Agile and Resilient Organizations with Sociocracy 3.0 is licensed to you under a Creative Commons Free Culture License. The exact license can be viewed here.

Basically this license grants you

1. Freedom to use the work itself.
2. Freedom to use the information in the work for any purpose, even commercially.
3. Freedom to share copies of the work for any purpose, even commercially.
4. Freedom to make and share remixes and other derivatives for any purpose.

You need to attribute the original creator of the materials, and all derivatives need to be shared under the same license. There's more on the topic of free culture on the Creative Commons website.