Address comments by @NewMexicoKid

Author: MaineC

project-setup/base-documentation.md

@@ -1,12 +1,15 @@
 # Title
 
-Standard base documentation
+Provide standard base documentation through a README
 
 # Context
 
 A project is to be shared with others as an InnerSource project. In order for
 others to be able to understand what the project is about as well as how to
-contribute, the project needs to provide some base level documentation.
+contribute, the project needs to provide some base level documentation. So far
+the project is lacking either all documentation or some aspects needed for users
+to try it out in a self-service manner as well as for contributors to get up to
+speed quickly.
 
 # Problem
 
@@ -19,14 +22,36 @@ exactly which colleagues are currently actively maintaining the project.
 
 # 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.
+  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.
+  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.
+  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
@@ -67,7 +92,7 @@ contain:
 If the explanation of the steps to make a contribution are too involved, create
 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
+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:
 
@@ -81,13 +106,20 @@ topics:
 * Some information on which turnaround time to expect for modifications made.
 
 
-There are literally tons of good examples for how to write a README.md and what kind
+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) all
-have valuable information on what kind of information to provide. In addition to that this
-pattern comes with two very basic templates to get you started right away.
+the book [Producing Open Source](https://producingoss.com/en/producingoss.html)
+all have valuable information on what kind of information to provide. While
+Producing Open Source does not have a chapter on writing a good README per se,
+the [Getting Started
+chapter](https://producingoss.com/en/producingoss.html#starting-from-what-you-have)
+does provide a fairly extensive list of things that fellow host team members,
+users and contributors will need. InnerSource projects likely will not cover all
+of those aspects right from the start, the list itself is helpful for
+inspiration for what one could cover. In addition to that, this pattern comes
+with two very basic templates to get you started right away.
 
 # Resulting Context