Skip to content

Commit a8ef821

Browse files
NewMexicoKidNewMexicoKid
authored
Merge pull request #122 from MaineC/basic-setup
Add first pattern on base documentation.
2 parents 470797a + 72927fe commit a8ef821

File tree

3 files changed

+280
-0
lines changed

3 files changed

+280
-0
lines changed

‎project-setup/base-documentation.md

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Title
2+
3+
Provide standard base documentation through a README
4+
5+
# Context
6+
7+
A project is to be shared with others as an InnerSource project. In order for
8+
others to be able to understand what the project is about as well as how to
9+
contribute, the project needs to provide some base level documentation. So far
10+
the project is lacking either all documentation or some aspects needed for users
11+
to try it out in a self-service manner as well as for contributors to get up to
12+
speed quickly.
13+
14+
# Problem
15+
16+
A team wants to share either a freshly started or a pre-existing project with
17+
the wider organization and receive contributions to it. Potential contributors
18+
often are lost: They are failing to identify the team's preferred communication
19+
channels. They have trouble quickly making a judgment about whether a new
20+
feature makes sense to be added or not. They have a hard time understanding
21+
exactly which colleagues are currently actively maintaining the project.
22+
23+
# Forces
24+
25+
- The project was converted into an InnerSource project only recently. Before,
26+
users were either only internal or on-boarded in personal face-to-face
27+
sessions. Equally, people working on the project went through personal
28+
on-boarding sessions which do not scale with growing numbers of contributors or
29+
remote contributors. As a result, self service documentation is lacking.
30+
- The project was newly created as an InnerSource project. However the host team
31+
lacks experience with InnerSource. As a result they need guidance on which
32+
information to include in their documentation, where to put that documentation
33+
so others can find it and which types of readers to address in their
34+
documentation.
35+
- The project was converted into an InnerSource project only recently, the host
36+
team has limited experience with InnerSource. As a result, existing
37+
documentation addresses a lot of technical aspects. It does not cover
38+
communication, coordination, information needed to facilitate transparent
39+
planning.
40+
- The project was converted into an InnerSource project only recently. As a
41+
result, a lot of implicit knowledge that exists within the team is neither
42+
written down nor obvious to contributors.
43+
- A lack of documentation leads to potential contributors taking a long time to
44+
get setup and get started. Producing documentation (and keeping it up to date)
45+
requires a time investment. Even if the host team relies on contributors to
46+
help with lacking documentation, those contributions still need time to review.
47+
- Project members are spending a lot of time answering getting started
48+
questions. Maintaining a comprehensive database of what could be considered
49+
support questions requires a lot of time and effort though.
50+
- Different teams within the organization have diverging standards for how to
51+
format source code and which software patterns to use. As a result
52+
contributions often end up getting re-written to a large part or even
53+
entirely. Standardizing all of that and enforcing the standard often
54+
would require a lot of time and work.
55+
- The added work for repeated explanations and re-writes diminishes the
56+
usefulness of the InnerSource approach.
57+
- Frequent escalations due to extra work and delays due to re-writes lead to a
58+
big cheese situation.
59+
60+
# Solution
61+
62+
Address the need for clearer documentation for new contributors. The goal when
63+
creating this documentation should be to make getting started as much a self
64+
service process as possible with frequently asked questions answered in standard
65+
documentation format.
66+
67+
If it does not yet exist, create a **README.md** for your project. It should
68+
contain:
69+
70+
* The [mission of the
71+
project](https://producingoss.com/en/producingoss.html#mission-statement) in
72+
as a concise format as possible. It should answer what the project's purpose
73+
is and enable contributors to make a good first guess whether a suggested
74+
feature will likely be in scope for the project, or not.
75+
* A "Getting Started" section for downstream users of the project. It should
76+
explain how to setup/ integrate the project artifacts as well as an
77+
explanation of some of the first typical steps for first time users.
78+
* Deeper documentation for project users - or a link to that.
79+
* Documentation needed for making modifications to the project - or a link to
80+
that.
81+
* Documentation on how to contribute to the project - or a link to that.
82+
* A "Getting involved" section that explains which public, archived, linkable
83+
communication channels the project uses. This should include a link to the
84+
project issue tracker, but also to any further discussion media used.
85+
* A "Who we are" section explaining who the Trusted Committers behind the
86+
project are - with an explanation that instead of contacting these people
87+
privately the public communication channels above should be used for
88+
communication.
89+
* An explanation of what the criteria are for the project to turn contributors
90+
into Trusted Committers - if that path exists.
91+
92+
If the explanation of the steps to make a contribution are too involved, create
93+
a separate **CONTRIBUTING.md** document. This document should answer frequently
94+
asked questions that contributors have asked in the past. There is no need to
95+
provide a comprehensive book up front. Rather, share information that has proven
96+
needed by contributors. Likely it will touch upon one or more of the following
97+
topics:
98+
99+
* How to checkout the project source code from version control.
100+
* How to make modifications to the project (potentially including information on
101+
coding guidelines.)
102+
* How to build the project.
103+
* How to run tests to make sure the above modifications aren't introducing new
104+
bugs.
105+
* How to submit your modifications back to the project.
106+
* Some information on which turnaround time to expect for modifications made.
107+
108+
109+
There are many of good examples for how to write a README.md and what kind
110+
of information to include in a CONTRIBUTING.md file in various open source projects.
111+
Pages like [how to write a readme that rocks](https://m.dotdev.co/how-to-write-a-readme-that-rocks-bc29f279611a),
112+
[Open Source Guide from GitHub](https://opensource.guide/) as well as
113+
the book [Producing Open Source](https://producingoss.com/en/producingoss.html)
114+
all have valuable information on what kind of information to provide. While
115+
Producing Open Source does not have a chapter on writing a good README per se,
116+
the [Getting Started
117+
chapter](https://producingoss.com/en/producingoss.html#starting-from-what-you-have)
118+
does provide a fairly extensive list of things that fellow host team members,
119+
users and contributors will need. InnerSource projects likely will not cover all
120+
of those aspects right from the start, the list itself is helpful for
121+
inspiration for what one could cover. In addition to that, this pattern comes
122+
with two very basic templates to get you started right away.
123+
124+
# Resulting Context
125+
126+
* The time for contributors to get up to speed is significantly reduced.
127+
* Time spent on answering initial questions for Trusted Committers is
128+
significantly reduced leaving them more time to work on other tasks.
129+
* Escalations due to misunderstandings and misalignment are significantly
130+
reduced.
131+
132+
# Known Instances
133+
134+
Europace AG, Paypal Inc.
135+
136+
# Authors
137+
138+
* Isabel Drost-Fromm
139+
140+
# Acknoledgements
141+
142+
143+
# State
144+
145+
Drafted in December 2019.

‎project-setup/templates/CONTRIBUTING-template.md

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Contributing to ____
2+
3+
## Types of contributions
4+
5+
Provide information on what kinds of contributions your project is looking for
6+
here. For example these can be bug reports, help with answering user questions,
7+
improving documentation, fixes to bugs, as well as new feature implementations.
8+
9+
## Bug reports
10+
11+
Add information on how to submit bug reports here. This should include
12+
hints about which type of information the project will need in order to
13+
reproduce and fix issues. It can also include information on commonly found
14+
mis-configurations that look like bugs.
15+
16+
Also include information on what contributors can expect in terms of time to
17+
first response and process after that.
18+
19+
## Feature requests
20+
21+
Add information on how to submit feature requests here. Also include information
22+
on what contributors can expect in terms of time to first response and process
23+
after that.
24+
25+
## Contributing documentation
26+
27+
Include information on any documentation best practices your project follows as
28+
well as how to build documentation, checks to run and how to submit the changes
29+
made back to the project.
30+
31+
## Contributing source code
32+
33+
This section should contain information on
34+
35+
- How to access the project source code,
36+
- General project layout,
37+
- Any requirements to the development environment,
38+
- Code formatting guidelines,
39+
- How to run the test suite.
40+
41+
## How to become a Trusted Committer
42+
43+
This section should make the process for becoming a Trusted Committer explicit
44+
if that route is open to contributors.
45+
## How to nominate Trusted Committers
46+
47+
This section serves as a reminder to existing and explanation for new Trusted
48+
Committers detailing how to add others to the host team. Again ideally this
49+
information is identical for all projects in the organisation so central
50+
information can be linked to from here.
51+

‎project-setup/templates/README-template.md

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Insert the name of your project here
2+
3+
## Mission
4+
5+
This should contain a brief (3-5 sentences) description of the mission of your
6+
project. The goal is to state what you are planning to work on and help external
7+
contributors understand roughly which types of features will likely be welcome
8+
for this project.
9+
10+
See also [mission statement
11+
chapter](https://producingoss.com/en/producingoss.html#mission-statement) in
12+
Producing Open Source Software.
13+
14+
## Getting Started
15+
16+
This section should contain brief documentation written for first time users on
17+
how to get started using the project. Further more detailed documentation can be
18+
linked to from here.
19+
20+
## Further information
21+
22+
This section can list any or all of the following:
23+
24+
* A list of features, use cases that the software addresses.
25+
* Information on design principles that are used to resolve trade-offs
26+
* Links to further user level documentation
27+
* Answers to frequently asked questions (FAQ), preferably in a format that
28+
allows to link to specific questions and their answers for easier reference.
29+
30+
## Getting help
31+
32+
This section should contain a brief documentation on how to get help for the
33+
project as a user. This could be as simple as pointing users to the issue
34+
tracker if this is how your project would like to answer questions. It could
35+
also point to an archived and searchable chat channel, some archived searchable
36+
mailing list, some online user forum.
37+
38+
## Getting involved
39+
40+
This section should include information on how to get in touch with the project:
41+
Typically this will contain links to archived, searchable and linkable
42+
communication channels.
43+
44+
## Who we are
45+
46+
This is a good place to give credit to Trusted Committers of the project.
47+
48+
It's also a good place to include information on what being a Trusted Committer
49+
means for this project - although ideally all projects in an organisation use
50+
the same definition that is only linked to from here. The reason to keep the
51+
link here is for colleagues who have no or little experience with working in and
52+
contributing to InnerSource projects to have a direct link back to company wide
53+
information from the technological projects they need for their daily work.
54+
55+
## Contributing
56+
57+
This section should document (or link to documentation) on all things that a
58+
first time contributor needs to know to get started. Typically not all of the
59+
topics below will be covered. Focus on what differs in your project from
60+
standard setup and what previous contributors found hard to understand.
61+
62+
- Finding the source code.
63+
- Finding a list of issues that your project needs help with - these can be
64+
both, technical and non-technical issues. Typically you will keep those in an
65+
issue tracker accessible to contributors.
66+
- Links to further documentation e.g. about the architecture of the project,
67+
general coding conventions, testing conventions...
68+
- For technical contributions: Making changes, building the project and testing
69+
your changes.
70+
- Submitting your changes back to the project.
71+
72+
Ideally you also include information on what the preferred process for changes
73+
looks like for the project: Should contributors first open an issue and submit a
74+
proposal, or are they welcome to submit changes right away? What is important to
75+
you when reviewing contributions?
76+
77+
In addition you should outline any design values you want to follow in the
78+
project. Making those explicit often helps resolve trade-offs more quickly and
79+
more easily. In addition it helps making changes to otherwise implicit
80+
assumptions transparent.
81+
82+
Over time you will notice that this section grows substantially. In that case
83+
think about moving the information to separate files, e.g. a CONTRIBUTING.md and
84+
TESTING.md

0 commit comments

Comments
 (0)