Review patterns from Europace. Changes mostly focused on correct formatting in our gitbook. (#260)

In detail:
- remove line-breaks in lists, as otherwise the list items don't use the full width of the book pages. extra line-breaks in lists may also lead to broken links
- link to other patterns where possible
- format file names with filename syntax
- introducing sub-sections for both README.md and CONTRIBUTING.md
- further minor typos and formatting inconsistencies

Author: spier

README.md

@@ -40,6 +40,9 @@ The below lists all known patterns. They are grouped into three [maturity levels
 * [Service vs. Library](patterns/2-structured/service-vs-library.md) - *Teams in a DevOps environment may be reluctant to work across team boundaries on common code bases due to ambiguity over who will be responsible for responding to service downtime. The solution is to realize that often it's
 possible to either deploy the same service in independent environments with separate escalation chains in the event of service downtime or factor a lot of shared code out into one library and collaborate on that.*
 * [Trusted Committer](patterns/2-structured/trusted-committer.md) - *Many inner-source projects will find themselves in a situation where they consistently receive feedback, features, and bug-fixes from contributors. In these situations project maintainers seek ways to recognize and reward the work of the contributor above and beyond single contributions.*
+* [Standard Base Documentation](patterns/2-structured/project-setup/base-documentation.md) - *New contributors to an InnerSource project have a hard time figuring out who maintains the project, what to work on, and how to contribute. Providing documentation in standard files like README.md/CONTRIBUTING.md enables a self service process for new contributors, so that they can find the answers to the most common questions on their own.*
+* [Issue Tracker Use Cases](patterns/2-structured/project-setup/issue-tracker.md) - *The InnerSource host team fails to make not only plans and progress but also context for changes transparent. This is solved by increasing the use cases for the project issue tracker to also serve brainstorming, implementation discussion, and feature design.*
+* [Communication Tooling](patterns/2-structured/project-setup/communication-tooling.md) - *An InnerSource project is being used outside the original development team but users are having trouble getting help and getting in touch with the project team. The idea is to setup and document standard communication tooling that allows for discussions to become visible, archived and searchable.*
 
 #### Pattern Drafts (proven, not yet fully reviewed)
 
@@ -50,9 +53,6 @@ possible to either deploy the same service in independent environments with sepa
 * [Open Source Trumps InnerSource](https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/46) - *People find the InnerSource project but, after all things are considered, even if the InnerSource component meets their needs, they still go with the open source component.*
 * [Start as Experiment](patterns/2-structured/start-as-experiment.md) - *An inner source initiative is considered but not started, because management is unsure about its outcome and therefore unwilling to commit to the investment.*
 * [Include Product Owners](https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/71) - *Key Performance Indicators (KPIs) for Product Owners are primarily product focused, and don't consider areas such as collaborative development. This results in a lower level of engagement with inner source projects.*
-* [Standard Base Documentation](patterns/2-structured/project-setup/base-documentation.md) - *New contributors to an InnerSource project have a hard time figuring out who maintains the project, what to work on, and how to contribute. Providing documentation in standard files like README.md/CONTRIBUTING.md enables a self service process for new contributors, so that they can find the answers to the most common questions on their own.*
-* [Issue Tracker Use Cases](patterns/2-structured/project-setup/issue-tracker.md) - *The InnerSource host team fails to make not only plans and progress but also context for changes transparent. This is solved by increasing the use cases for the project issue tracker to also serve brainstorming, implementation discussion, and feature design.*
-* [Communication Tooling](patterns/2-structured/project-setup/communication-tooling.md) - *An InnerSource project is being used outside the original development team but users are having trouble getting help and getting in touch with the project team. The idea is to setup and document standard communication tooling that allows for discussions to become visible, archived and searchable.*
 
 ### Maturity Level 1: Initial
 

patterns/2-structured/project-setup/base-documentation.md

@@ -6,7 +6,7 @@ Standard Base Documentation
 
 New contributors to an InnerSource project have a hard time figuring out who
 maintains the project, what to work on, and how to contribute. Providing
-documentation in standard files like README.md/CONTRIBUTING.md enables a
+documentation in standard files like `README.md`/`CONTRIBUTING.md` enables a
 self service process for new contributors, so that they can find the answers to
 the most common questions on their own.
 
@@ -30,40 +30,15 @@ speed quickly.
 
 ## Forces
 
-- The project was converted into an InnerSource project only recently. Before,
-  users were either only internal or on-boarded in personal face-to-face
-  sessions.  Equally, people working on the project went through personal
-  on-boarding sessions which do not scale with growing numbers of contributors or
-  remote contributors. As a result, self service documentation is lacking.
-- The project was newly created as an InnerSource project. However the host team
-  lacks experience with InnerSource. As a result they need guidance on which
-  information to include in their documentation, where to put that documentation
-  so others can find it and which types of readers to address in their
-  documentation.
-- The project was converted into an InnerSource project only recently, the host
-  team has limited experience with InnerSource. As a result, existing
-  documentation addresses a lot of technical aspects. It does not cover
-  communication, coordination, information needed to facilitate transparent
-  planning.
-- The project was converted into an InnerSource project only recently. As a
-  result, a lot of implicit knowledge that exists within the team is neither
-  written down nor obvious to contributors.
-- A lack of documentation leads to potential contributors taking a long time to
-  get setup and get started. Producing documentation (and keeping it up to date)
-  requires a time investment. Even if the host team relies on contributors to
-  help with lacking documentation, those contributions still need time to review.
-- Project members are spending a lot of time answering getting started
-  questions. Maintaining a comprehensive database of what could be considered
-  support questions requires a lot of time and effort though.
-- Different teams within the organization have diverging standards for how to
-  format source code and which software patterns to use. As a result
-  contributions often end up getting re-written to a large part or even
-  entirely. Standardizing all of that and enforcing the standard often
-  would require a lot of time and work.
-- The added work for repeated explanations and re-writes diminishes the
-  usefulness of the InnerSource approach.
-- Frequent escalations due to extra work and delays due to re-writes lead to a
-  big cheese situation.
+- The project was converted into an InnerSource project only recently. Before, users were either only internal or on-boarded in personal face-to-face sessions. Equally, people working on the project went through personal on-boarding sessions which do not scale with growing numbers of contributors or remote contributors. As a result, self service documentation is lacking.
+- The project was newly created as an InnerSource project. However the host team lacks experience with InnerSource. As a result they need guidance on which information to include in their documentation, where to put that documentation so others can find it and which types of readers to address in their documentation.
+- The project was converted into an InnerSource project only recently, the host team has limited experience with InnerSource. As a result, existing documentation addresses a lot of technical aspects. It does not cover communication, coordination, information needed to facilitate transparent planning.
+- The project was converted into an InnerSource project only recently. As a result, a lot of implicit knowledge that exists within the team is neither written down nor obvious to contributors.
+- A lack of documentation leads to potential contributors taking a long time to get setup and get started. Producing documentation (and keeping it up to date) requires a time investment. Even if the host team relies on contributors to help with lacking documentation, those contributions still need time to review.
+- Project members are spending a lot of time answering getting started questions. Maintaining a comprehensive database of what could be considered support questions requires a lot of time and effort though.
+- Different teams within the organization have diverging standards for how to format source code and which software patterns to use. As a result contributions often end up getting re-written to a large part or even entirely. Standardizing all of that and enforcing the standard often would require a lot of time and work.
+- The added work for repeated explanations and re-writes diminishes the usefulness of the InnerSource approach.
+- Frequent escalations due to extra work and delays due to re-writes lead to a big cheese situation.
 
 ## Solution
 
@@ -72,52 +47,40 @@ creating this documentation should be to make getting started as much a self
 service process as possible with frequently asked questions answered in standard
 documentation format.
 
-If it does not yet exist, create a **README.md** for your project. It should
+### README.md
+
+If it does not yet exist, create a `README.md` for your project. It should
 contain:
 
-* The [mission of the
-  project](https://producingoss.com/en/producingoss.html#mission-statement) in
-  as a concise format as possible. It should answer what the project's purpose
-  is and enable contributors to make a good first guess whether a suggested
-  feature will likely be in scope for the project, or not.
-* A "Getting Started" section for downstream users of the project. It should
-  explain how to setup/ integrate the project artifacts as well as an
-  explanation of some of the first typical steps for first time users.
+* The [mission of the project](https://producingoss.com/en/producingoss.html#mission-statement) in as a concise format as possible. It should answer what the project's purpose is and enable contributors to make a good first guess whether a suggested feature will likely be in scope for the project, or not.
+* A "Getting Started" section for downstream users of the project. It should explain how to setup/ integrate the project artifacts as well as an explanation of some of the first typical steps for first time users.
 * Deeper documentation for project users - or a link to that.
-* Documentation needed for making modifications to the project - or a link to
-  that.
+* Documentation needed for making modifications to the project - or a link to that.
 * Documentation on how to contribute to the project - or a link to that.
-* A "Getting involved" section that explains which public, archived, linkable
-  communication channels the project uses. This should include a link to the
-  project issue tracker, but also to any further discussion media used.
-* A "Who we are" section explaining who the Trusted Committers behind the
-  project are - with an explanation that instead of contacting these people
-  privately the public communication channels above should be used for
-  communication.
-* An explanation of what the criteria are for the project to turn contributors
-  into Trusted Committers - if that path exists.
+* A "Getting involved" section that explains which public, archived, linkable communication channels the project uses. This should include a link to the project issue tracker, but also to any further discussion media used.
+* A "Who we are" section explaining who the [Trusted Committers](../trusted-committer.md) behind the project are - with an explanation that instead of contacting these people privately the public communication channels above should be used for communication.
+* An explanation of what the criteria are for the project to turn contributors into Trusted Committers - if that path exists.
+
+### CONTRIBUTING.md
 
 If the explanation of the steps to make a contribution are too involved, create
-a separate **CONTRIBUTING.md** document. This document should answer frequently
+a separate `CONTRIBUTING.md` document. This document should answer frequently
 asked questions that contributors have asked in the past. There is no need to
 provide a comprehensive book up front. Rather, share information that has proven
 needed by contributors. Likely it will touch upon one or more of the following
 topics:
 
 * How to checkout the project source code from version control.
-* How to make modifications to the project (potentially including information on
-  coding guidelines.)
+* How to make modifications to the project (potentially including information on coding guidelines).
 * How to build the project.
-* How to run tests to make sure the above modifications aren't introducing new
-  bugs.
+* How to run tests to make sure the above modifications aren't introducing new bugs.
 * How to submit your modifications back to the project.
 * Some information on which turnaround time to expect for modifications made.
 
 ![Brief picture of README.md and CONTRIBUTING.md content](./assets/base_docs_drawing.png)
 
-
-There are many of good examples for how to write a README.md and what kind
-of information to include in a CONTRIBUTING.md file in various open source projects.
+There are many of good examples for how to write a `README.md` and what kind
+of information to include in a `CONTRIBUTING.md` file in various open source projects.
 Pages like [how to write a readme that rocks](https://m.dotdev.co/how-to-write-a-readme-that-rocks-bc29f279611a),
 [Open Source Guide from GitHub](https://opensource.guide/) as well as
 the book [Producing Open Source](https://producingoss.com/en/producingoss.html)
@@ -137,10 +100,8 @@ started right away: [README-template.md](templates/README-template.md) and
 ## Resulting Context
 
 * The time for contributors to get up to speed is significantly reduced.
-* Time spent on answering initial questions for Trusted Committers is
-  significantly reduced leaving them more time to work on other tasks.
-* Escalations due to misunderstandings and misalignment are significantly
-  reduced.
+* Time spent on answering initial questions for [Trusted Committers](../trusted-committer.md) is significantly reduced, leaving them more time to work on other tasks.
+* Escalations due to misunderstandings and misalignment are significantly reduced.
 
 ## Known Instances
 
@@ -151,8 +112,6 @@ started right away: [README-template.md](templates/README-template.md) and
 
 * Isabel Drost-Fromm
 
-## Acknowledgements
-
 ## Alias
 
 Provide standard base documentation through a README

patterns/2-structured/project-setup/communication-tooling.md

@@ -25,12 +25,9 @@ answer.
 
 ## Forces
 
-- The host team is interested in receiving contributions and willing to mentor
-  contributors.
-- Teams have a strong verbal communication culture and are inexperienced with
-  setting up project specific asynchronous communication channels.
-- Communication channels may be aligned with specific groups that should be
-  reached but not by communication purpose.
+- The host team is interested in receiving contributions and willing to mentor contributors.
+- Teams have a strong verbal communication culture and are inexperienced with setting up project specific asynchronous communication channels.
+- Communication channels may be aligned with specific groups that should be reached but not by communication purpose.
 
 ## Solution
 
@@ -42,24 +39,14 @@ The goal when streamlining communication channels for InnerSource projects
 should be to align communication around topics, not around certain sets of
 people:
 
-- The project should have it's own issue tracker where structured communication,
-  decision making and progress tracking can happen transparently for all host
-  team members but also for downstream users and contributors to follow.
-- The project should have one or more discussion channels that come with less
-  rigid a structure. Typically this will be mailing lists, online forums or even
-  archived chat channels. Usually it is enough to start with just one channel
-  for the project, if traffic increases too much it's helpful to split
-  discussions around project usage from discussions around project development.
-- In addition the project should have one private channel where sensitive
-  communication can happen between Trusted Committers - e.g. adding further
-  Trusted Committers to the host team. This channel should be used with great
-  care such that communication defaults to open and is kept private only under
-  very rare circumstances.
+- The project should have it's own issue tracker where structured communication, decision making and progress tracking can happen transparently for all host team members but also for downstream users and contributors to follow.
+- The project should have one or more discussion channels that come with less rigid a structure. Typically this will be mailing lists, online forums or even archived chat channels. Usually it is enough to start with just one channel for the project, if traffic increases too much it's helpful to split discussions around project usage from discussions around project development.
+- In addition the project should have one private channel where sensitive communication can happen between [Trusted Committers](../trusted-committer.md) - e.g. adding further Trusted Committers to the host team. This channel should be used with great care such that communication defaults to open and is kept private only under very rare circumstances.
 
 While communication can happen outside of written channels, as much information
 as possible should be brought back to the asynchronous channels.
 
-All communication channels should be documented in the project README.md The
+All communication channels should be documented in the project `README.md`. The
 host team members need to make an effort to direct questions that they receive
 personally back to official communication channels.