Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add first pattern on base documentation. #122

Open
wants to merge 8 commits into
base: master
from

Conversation

@MaineC
Copy link
Collaborator

MaineC commented Dec 18, 2019

This relates to #114

It takes a first stab at writing up the basics of InnerSource project setup starting with adding base documentation.

Essentially this is based on experience shared on our company blog at http://tech.europace.de

While the components of basic project documentation are mentioned in the InnerSource Checklist book I think it makes sense to also include them in our pattern language so people have one place to look for best practices.

This relates to #114

It takes a first stab at writing up the basics of InnerSource project setup
starting with adding base documentation.
Copy link
Collaborator

rrrutledge left a comment

Looks great to me. Thanks for documenting, Isabel.

@rrrutledge

This comment has been minimized.

Copy link
Collaborator

rrrutledge commented Dec 18, 2019

@lenucksi had talked at one point about even providing README and CONTRIBUTING templates to help people to implement this pattern.

Or maybe there are some templates out there already to which we can link.

@MaineC

This comment has been minimized.

Copy link
Collaborator Author

MaineC commented Dec 18, 2019

Adding templates for this is a really good idea. Unless I find some elsewhere, I'll create them and add/ link to them as part of this pull request.

@rrrutledge

This comment has been minimized.

Copy link
Collaborator

rrrutledge commented Dec 18, 2019

Yes! Thank you!

These templates are meant to be used as a starting point for creating project
documentation. Likely for smaller projects following standard coding practices
their content can be reduced. The more experience the project has with working
with contributors the more helpful those documents will get.
Copy link
Collaborator

rrrutledge left a comment

Very nice and useful!

@@ -0,0 +1,40 @@
# Contributing to ____

This comment has been minimized.

Copy link
@rrrutledge

rrrutledge Dec 19, 2019

Collaborator

This is great, but surely there must be an open-source template that we can link to? Nothing here looks unique to InnerSource.

This comment has been minimized.

Copy link
@MaineC

MaineC Dec 20, 2019

Author Collaborator

I haven't looked for contributing templates. For READMEs I usually forward people to

https://m.dotdev.co/how-to-write-a-readme-that-rocks-bc29f279611a

I wonder if any of the bigger foundations have templates for these things that we can link to.

A ton of wisdom on how to run an open source project is also in https://producingoss.com/en/producingoss.html

There's also the following from GitHub, which if you click through leads to a more detailed explanation of what belongs into a contributing file.

I'm sure there are others that I'm not aware of. A lot of the things I've written down come from practical experience in open source projects.

This comment has been minimized.

Copy link
@MaineC

MaineC Jan 8, 2020

Author Collaborator

I have added links to these sites to the pattern itself - also added that often it's a good idea to check what open source projects include in their docs.

This comment has been minimized.

Copy link
@lenucksi

lenucksi Jan 27, 2020

Member

I had a bunch of links researched when I wrote mine, maybe I'll find some notes or bookmarks of that.
And yes, there were quite a few very nice things.

contributing to InnerSource projects to have a direct link back to company wide
information from the technological projects they need for their daily work.

### How to become a Trusted Committer

This comment has been minimized.

Copy link
@rrrutledge

rrrutledge Dec 19, 2019

Collaborator

These sections on trusted committer management seem less important than contributing guides - suggest they go under the Contributing section.

information is identical for all projects in the organisation so central
information can be linked to from here.

## Contributing

This comment has been minimized.

Copy link
@rrrutledge

rrrutledge Dec 19, 2019

Collaborator

Could use something about how to get help (chat/mailing-list/etc)?

This comment has been minimized.

Copy link
@MaineC

MaineC Jan 8, 2020

Author Collaborator

Makes sense. I've added some information on that.

Copy link

ElisaBaum left a comment

LGTM

project-setup/base-documentation.md Outdated Show resolved Hide resolved
See also [mission statement
chapter](https://producingoss.com/en/producingoss.html#mission-statement) in
Producing Open Source Software.

This comment has been minimized.

Copy link
@martinklewitz

martinklewitz Dec 23, 2019

This could include properties and qualities that want to be achieved in this project. Some of those qualities can be very specific and may be changed over the lifetime of the project. They help identify what the project wants to achieve and how what tradeoffs are chosen. For example "in order to strive for simplicity and performance we may not implement feature request that improve convenience".

This comment has been minimized.

Copy link
@MaineC

MaineC Jan 8, 2020

Author Collaborator

I believe this goes a bit too far for a mission statement. However I believe this is valuable information to include. I have moved it to the contributing section as it is information that contributors will need to make in informed decision about whether their change will be accepted or not.

Writing this text down, I've come to think that this may well be interesting to users who never thought about contributing as well - it could well help decide whether or not to adopt the software.

Likely the template needs some more user focused information.

Copy link

martinklewitz left a comment

Looks good.

MaineC and others added 4 commits Jan 7, 2020
Co-Authored-By: Elisa Baum <elisabaum@hotmail.com>
This adds links to external existing documentation on what information to include in a README.md and a contributing guide. While those links point to help for open source projects, most of the information they provide are relevant to InnerSource projects as well.
This moves the "becoming a committer" section to the contributing doc. It also
adds a section on getting help. In addition it adds a requirement to make
project design values explicit to the contributing section.
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

This comment has been minimized.

Copy link
@rrrutledge

rrrutledge Jan 8, 2020

Collaborator

I don't actually see good information on a README at the Producing OSS link. Am I just missing it?

This comment has been minimized.

Copy link
@MaineC

MaineC Jan 9, 2020

Author Collaborator

There is no chapter on writing a good README. The book doesn't say which form to choose to provide the documentation that is often (but not always) found in or linked to in a README.

However in the Getting Started Chapter (https://producingoss.com/en/producingoss.html#starting-from-what-you-have) it does provide a fairly extensive list of things that fellow host team members, users and contributors will need. I don't expect an InnerSource project to cover all of those aspects in their documentation - I find the list helpful as inspiration for what one could cover.

This comment has been minimized.

Copy link
@NewMexicoKid

NewMexicoKid Jan 24, 2020

Collaborator

I would suggest you add this clarification to the producingoss link so people know what to expect and what to look for. E.g., ... as well as the book Producing Open Source (although the book doesn't say which form to choose to provide the documentation often found in a README, the Getting Started Chapter does provide a fairly extensive list of things that fellow host team members, users and contributors will need).

@MaineC

This comment has been minimized.

Copy link
Collaborator Author

MaineC commented Jan 21, 2020

Does this need the "Do 2nd review" label?

@rrrutledge

This comment has been minimized.

Copy link
Collaborator

rrrutledge commented Jan 21, 2020

I suppose so!

@MaineC

This comment has been minimized.

Copy link
Collaborator Author

MaineC commented Jan 22, 2020

Would be nice if someone added it - I can't do that as a contributor.

Copy link
Collaborator

NewMexicoKid left a comment

This is a nice pattern. You might consider naming it: Provide standard base documentation through a README
I would suggest a little more analysis on the forces as the ones presented make it a no-brainer to create a README; there must be some forces that result in the initial context where there is no standard base documentation for the IS project.

* 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

This comment has been minimized.

Copy link
@NewMexicoKid

NewMexicoKid Jan 24, 2020

Collaborator

I think there are not literally tons; suggest replacing 'literally tons of' with 'many'

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

This comment has been minimized.

Copy link
@NewMexicoKid

NewMexicoKid Jan 24, 2020

Collaborator

I would suggest you add this clarification to the producingoss link so people know what to expect and what to look for. E.g., ... as well as the book Producing Open Source (although the book doesn't say which form to choose to provide the documentation often found in a README, the Getting Started Chapter does provide a fairly extensive list of things that fellow host team members, users and contributors will need).


# Forces

- A lack of documentation leads to potential contributors taking a long time to

This comment has been minimized.

Copy link
@NewMexicoKid

NewMexicoKid Jan 24, 2020

Collaborator

All of these forces are driving one side of the problem (towards writing the documentation). Forces are constraints with trade-offs. The trade-offs here are only implied. E.g., A lack of documentation leads to potential contributors taking a long time to get setup and get started. Producing the documentation needed to help out potential contributors will require an investment of time and effort from the project owner.

I think it would be helpful to examine the list of forces (constraints on the problem and solution) to see what the trade-offs/costs are in each force dimension (which isn't to say that every force requires listing the trade-off explicitly, but the main ones should say something about this, IMHO).

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

This comment has been minimized.

Copy link
@NewMexicoKid

NewMexicoKid Jan 24, 2020

Collaborator

Suggest adding a comma after Rather.

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

This comment has been minimized.

Copy link
@NewMexicoKid

NewMexicoKid Jan 24, 2020

Collaborator

Suggest adding a comma after "that"
In addition to that, this ...


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.

This comment has been minimized.

Copy link
@NewMexicoKid

NewMexicoKid Jan 24, 2020

Collaborator

The context reflects the initial state, the one where we are before the solution (the README) is applied. I think there should be mention that not only is there a need for others to be able to understand what the project is about, but that there is no base level documentation (why that situation exists should be addressed in the Forces section).

@MaineC

This comment has been minimized.

Copy link
Collaborator Author

MaineC commented Jan 27, 2020

@NewMexicoKid Thank you for your kind and thorough review. I've learnt several more details about the pattern format that I wasn't aware of before.

I've tried to address your comments. Not sure if the changes I made are exactly on-point. I'd appreciate for you to have another look.

@sjn

This comment has been minimized.

Copy link

sjn commented Jan 27, 2020

Suggestion: say something about the target audience of the README file. Whose needs should the content of the file be tailored to? Typical audiences might include...

  • People who want to know if the project is relevant for them
  • Potential contributors
  • People who need a quick reminder on where to find further information

(I'm sure there are others :-) )

@lenucksi

This comment has been minimized.

Copy link
Member

lenucksi commented Jan 27, 2020

@lenucksi had talked at one point about even providing README and CONTRIBUTING templates to help people to implement this pattern.

Or maybe there are some templates out there already to which we can link.

I did, mine got stuck in bureaucracy. I'll help to create some that or see if we can maybe re-use some of the ones that I found while create the ones that got stuck in bureaucracy.

However I just saw that there great stuff in here already! :D

@lenucksi lenucksi added this to In progress in Pattern Processing via automation Mar 22, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Pattern Processing
  
In progress
Linked issues

Successfully merging this pull request may close these issues.

None yet

7 participants
You can’t perform that action at this time.