Merge pull request #431 from InnerSourceCommons/improve-book-docs

Improve docs of book/translation/contribution

Author: yuhattor

CONTRIBUTING.md

@@ -6,17 +6,22 @@ For this working group to strive, we welcome your contribution - be it small or
 
 ## How to Contribute?
 
-Please consider contributing in the following ways:
+Please consider contributing to the InnerSource Patterns.
+Here some ideas for ways to contribute:
 
 1. **Share your thoughts & spark discussion**. A fresh perspective, an interesting thought, or an early novel idea can spark discussions and yield unforeseeable results. We invite you to share your thoughts on InnerSource-related topics at any time by [creating an issue](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues/new), [via Slack, or our patterns office hours](#how-to-get-in-touch).
 
 2. **Read & improve existing patterns.** If you want to get started, we encourage you to read through the existing patterns and materials in this repository. Found a misleading phrase or phony grammar? A mistake in the content? Let us know by [creating an issue](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues/new) or directly propose your fix as a pull request.
 
-3. **Review open pull requests.** Even without knowing all the specifics of the patterns working group, your feedback on existing [pull requests](https://github.com/InnerSourceCommons/InnerSourcePatterns/labels/type%20-%20Content%20work) (especially those propising changes to pattern contents) will be valuable to its authors: As somebody who wants to learn more about InnerSource, you can give input from the perspective of a future reader. As somebody with own InnerSource experiences, you can share your experience with the authors.
+3. **Confirm that you are using a pattern** When multiple orgs confirm that they are using a pattern, that increases the relevance of the pattern as it lets other adopters known that this pattern is proven. If you are using one of our patterns, you can list your org as **Known Instance** on the given pattern, together with a description of the experiences that you made applying it. Here some examples of [great Known Instances descriptions](patterns/2-structured/document-your-guiding-principles.md#known-instances).
 
-4. **Contribute a new pattern.** A key contribution you can make is to document an InnerSource best practice you experienced or know about. We defined different maturity levels for the contents in this repository: First time contributors should aim for maturity levels `1: initial` (for unstructured experience reports or what we call donuts - patterns with missing pieces) and `2: structured` (for best practices adhering to the patterns format and following basic writing style conventions). Our [Contributor Handbook](meta/contributor-handbook.md) discusses all this in more detail. You don't feel ready yet to contribute a new pattern? Please start a discussion by [creating an issue](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues/new).
+4. **Translate existing patterns.** When implementing InnerSource practices in your region, there can be language barriers for people as most of the InnerSource content is available in English. Therefore we see great value in getting people in your region/organization to understand InnerSource in their own language. To help us translate patterns to other languages please refer to [these translation instructions](translation/README.md).
 
-5. **Be a patterns advocate.** The patterns will become better and cover more topics the more people contribute their perspective and experience. A colleague told you about a novel InnerSource best practice? Please invite her/him to contribute to this repository!
+5. **Review open pull requests.** Even without knowing all the specifics of the patterns working group, your feedback on existing [pull requests](https://github.com/InnerSourceCommons/InnerSourcePatterns/labels/type%20-%20Content%20work) (especially those proposing changes to pattern contents) will be valuable to its authors: As somebody who wants to learn more about InnerSource, you can give input from the perspective of a future reader. As somebody with own InnerSource experiences, you can share your experience with the authors.
+
+6. **Contribute a new pattern.** A key contribution you can make is to document an InnerSource best practice you experienced or know about. We defined different maturity levels for the contents in this repository: First time contributors should aim for maturity levels `1: initial` (for unstructured experience reports or what we call donuts - patterns with missing pieces) and `2: structured` (for best practices adhering to the patterns format and following basic writing style conventions). Our [Contributor Handbook](meta/contributor-handbook.md) discusses all this in more detail. You don't feel ready yet to contribute a new pattern? Please start a discussion by [creating an issue](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues/new).
+
+7. **Be a patterns advocate.** The patterns will become better and cover more topics the more people contribute their perspective and experience. A colleague told you about a novel InnerSource best practice? Please invite her/him to contribute to this repository!
 
 ## How to get in touch?
 

book/README.md

@@ -1,37 +1,43 @@
 # How to generate the InnerSource Patterns gitbook
 
-Whenever changes to the [InnerSource Patterns][InnerSourcePatterns] GitHub repository are made, a new version of our InnerSource Patterns book is published at [patterns.innersourcecommons.org][book_production].
+Whenever changes to the [InnerSource Patterns GitHub repository][InnerSourcePatterns] are made, a new version of the InnerSource Patterns book is published at [patterns.innersourcecommons.org][book_production].
 
 ## Where is the book published?
 
-The most up-to-date version of the book is available for readers at [patterns.innersourcecommons.org][book_production].
+The latest version of the book is available for readers at [patterns.innersourcecommons.org][book_production].
 
-We also have a [Staging version][book_staging], used by the editors/producers of the book for testing purposes. If you want to make any structural changes to the book, please send a PR to merge your changes into the `book-staging` branch. That way we can test your changes on the Staging version first, before they go live.
+We also have a [Staging version][book_staging], used by the editors/producers of the book for testing purposes. If you want to make structural changes to the book, please contact us via a GitHub issue first.
 
 ## Which patterns are published?
 
-The book contains patterns of maturity **Structured** (Level 2) or **Validated** (Level 3). **Initial** (Level 1) patterns are not published in the book, because those are still subject to a lot of change, and have likely not even proven to work yet. For more on these maturity levels see the [Contributor Handbook](../meta/contributor-handbook.md).
+The book contains patterns of maturity **Structured** (Level 2) or **Validated** (Level 3).
 
-## How does it work?
+**Initial** (Level 1) patterns are not published in the book. Those are still subject to a lot of change, and have likely not even proven to work yet. For more on these maturity levels see the [Contributor Handbook](../meta/contributor-handbook.md).
+
+## How does it work technically?
+
+We use the [gitbook.com](https://www.gitbook.com) service to host our book.
 
 The `/book` folder contains generator scripts and extra content required to create the gitbook.
 
 - `.github/workflows/book.yml` - A GitHub Action that triggers scripts to generate the book.
-- `/book/scripts/generate_toc.rb` - This script generates the table of contents (ToC) for the book. It takes patterns of maturity **Structured** and **Validated**, extracts title and patlet, and injects this info into `/book/en/toc_template.md`. The output is written to `/book/en/toc.md`. The ToC is what you see on the left-hand-side menu in the gitbook.
+- `/book/scripts/generate_toc.rb` - Generates the table of contents (ToC) for the book. It takes patterns of maturity **Structured** and **Validated**, extracts title and patlet, and injects this info into `/book/en/toc_template.md`. The output is written to `/book/en/toc.md`. The ToC is what you see on the left-hand-side menu in the gitbook.
 - `/book/en/.gitbook.yaml` - Holds basic configuration for the gitbook service. This file is copied to the root of the repo, if the English book is generated.
 - `/book/en/introduction.md` - The introduction to our book. This is what the reader sees first when they open the book. *Note:* The current content is based on [README.md](../README.md).
-- `/book/en/contribute.md` - Information about how to contribute to this book.
-- `/book/en/explore-patterns.md` - Show the mind map of all patterns. Allows readers to link to the mind map directly.
+- `/book/en/contribute.md` - Explains how to contribute to this book.
+- `/book/en/explore-patterns.md` - Shows the mind map of all patterns. Allows readers to link to the mind map directly.
 - patterns content:
   - The English patterns are in `/patterns`
   - The translated patterns (e.g. for Japanese) are in `/translation/japanese`
 
 The book is generated in multiple languages.
 
-The descriptions above are for the English book. You find the language specific content in `/book/en`.
+The descriptions above are for the English book. You find the English content in `/book/en`.
 
 For other languages (e.g. for Japanese), the content is mirrored and translated to folders like  `/book/jp`.
 
+For more on the translation process see [these translation instructions](../translation/README.md).
+
 ### Triggering the book generation
 
 The book is generated in multiple languages.

translation/README.md

@@ -11,24 +11,28 @@ Please note that this document contains recommendations, aimed at removing barri
 ## The Translation Principles and Recommendation
 
 - The target of the translation are structured patterns. Find them in folder [/patterns/2-structured/](../patterns/2-structured/). Only structured patterns will be published in Gitbook.
-- English is recommended for commit messages. If you are merged into a branch, your commit messages will be seen by members all over the world. This will make it easier for global members to find your activities and will also accelerate collaboration.
+- English is recommended for commit messages. If your changes are merged, your commit messages will be seen by members all over the world. This will make it easier for global members to find your activities and will also accelerate collaboration.
 - Regarding Pull Requests and Issues, it is a good idea to use English, at least for the title and the purpose statement in the preface. Contributions in your language and accompanying discussions may be useful for other translation projects in the future.
 - Each country has its own cultural and historical background and different contexts. There is no need to discuss language-specific nuances and difficult linguistic expressions in English in your review. Especially if it is a local community of several people translating together, please prioritize the ease of translation in that community.
 
 ## How to Contribute to the Translation
 
-### How to Improve an Existing Translation
+### Improving an Existing Translation
 
-- Please send your Pull Request.
+- Please make your changes to the respective `.md` file.
+- Once you are ready, send us a Pull Request.
 
-### How to translate new InnerSource Patterns
+### Translating a new InnerSource Patterns
 
 - Please copy the file `/patterns/2-structured/<file>.md` to `/translation/<language>/patterns/<file>.md` and start translation.
+- Once you are ready, send us a Pull Request.
 
-### How to Start Translating a New Language
+### Starting the Translation of a New Language
 
 That is awesome! We welcome your passion. When implementing InnerSource practices in your region, there can be language barriers. There is great value in getting people in your organization to understand InnerSource in their own language.
 
+Before starting a new translation please talk to us in Slack (in the `#innersource-patterns` channel). Alternatively you can also open an issue on this GitHub repo and we can have an async conversation about your translation project.
+
 The translation should begin by creating a `book-<YOUR_LANGUAGE>` branch to work on. Please name the branch after the abbreviation of the language e.g. `book-jp` is used for the Japanese version.
 
 There are a few things you should prepare before starting a translation project.
@@ -41,8 +45,14 @@ However, since git does not create empty folders, it is better to create directo
 
 ### Translation Quality and Review Process
 
-- There is a best practice to have at least one native speaker review the translation. In particular, for some special terms, such as "Trusted Committer", please review not only for grammatical correctness but also for appropriateness. If you find a term or expression difficult to understand, please don't hesitate to ask.
+We consider it best practice to have **at least one native speaker** review the translation.
+
+In particular, for special terms, such as "Trusted Committer", please review not only for grammatical correctness but also for appropriateness. If you find a term or expression difficult to understand, please don't hesitate to ask.
 
 ### Publishing Translations
 
-The books currently available are in English and Japanese. Trusted Committers in this repository will also be onboarded during the translation process. When you complete a translation under `/translation/<YOUR_LANGUAGE>/`, a GitHub Actions pipeline will run to generate the output for publication in the gitbook. The detailed process is described in [/book/README.md](/book/README.md). Please refer to it.
+The books currently available are in English and Japanese.
+
+Trusted Committers in this repository will also be onboarded during the translation process.
+
+When you complete a translation under `/translation/<YOUR_LANGUAGE>/`, a GitHub Actions pipeline will run to generate the output for publication in the gitbook. The process is described in detail in [/book/README.md](/book/README.md).