WIP intro principles

[demianbrecht]

Work in progress, wanted to get at least the rough version up before tomorrow's meeting.

[rrrutledge]

Thanks for sharing this, Demian. What kind of review do you want on what's been written so far?

[demianbrecht]

Full review is fine. I prefer to fail fast :)

[rrrutledge]

I don't know exactly where this belongs, but I feel like in the end if a project is open and transparent then there becomes less and less difference between the way the Host team members interact with the project and the way that any Contributor interacts with the project. The process by which the Host team interacts in prioritizing, reviewing, or changing the project is the same process that any interested Contributor could do.

That's not a specific suggestion, but wondering what you all thought about incorporating that ethos into some of what's been written, here?

[KathrynKLewis]

Please review and consider my edits.

[demianbrecht]

@rrrutledge apologies for taking so long to get to your comment, but I'm not quite sure that's going to be true in all situations. Even if a project is open and transparent, there may be mechanics that are abstracted from contributors in order to expose a standardized interface for collaborators with the intention of facilitating contributions.

From a tools perspective, a company may use project management software outside of Github issue tracker. It's possible that teams within a company will use that software entirely differently than other teams. In order to facilitate inner sourcing, they may agree to standardize on using Github issue trackers for inner source-specific issues, thereby skirting around the need for contributors to become familiar with each team's process around project management.

From a workflow perspective in terms of feature requests, I would imagine that a contributor would propose a new feature and the owning team would discuss it amongst themselves to evaluate whether or not this new feature aligns with their project roadmap. They would then either accept the proposal, request changes or flat out deny it.

In either case, the host team and contributors still have very different experiences when working on and making changes to the project. So I'm not sure that should be included in the ethos here.

[rrrutledge]

Would there be a way for contributors to grow to interact with others on the Host team in the same way or will there forever be some aspects of the project that are only accessible to people in a certain section of management hierarchy?

[demianbrecht]

@KathrynKLewis I've pushed a new commit with your proposals incorporated.

[demianbrecht]

@rrrutledge honestly I'm not sure. Solely based on my exposure to my current corporate environment, I think that there will always be a divide between guest and host contributors, until the time that a guest contributor becomes a part of the host team within the organization. I think guest contributors will have varying degrees of influence based on their contributions, but I don't think they'll have the same experience as the host team.

Looking at it from a different angle, if host and guest team were to have identical experiences in project contributions, that may mean (depending on company or team approaches) that a guest contributor /should/ be part of team planning sessions, which may take a large amount of time (hours, days, weeks depending on the complexity). I'd see it being a challenge to have management approve spending that amount of time with a team potentially entirely disconnected from their own requirements and deliverables (even though they may be a dependent).

Then there are chains of command. Should guest contributors be exposed to upper level management requirements passed down from on high? I feel that if that can of worms is opened, then the guest contributor's time may be swallowed up (again, very organization dependent) to the point where contributions are disallowed by their own management due to the inability to complete their own deliverables. I think that host teams need to provide /some/ level of insulation for guest contributors and filter out noise that isn't directly applicable to the problem(s) that the guest contributors are trying to solve.

I think that while what you're talking about is an ideal situation and very much akin to open source development, I can't see it being realistic in most corporate settings. If such a contributor model exists or is created, my guess is that it would be an exception and not the rule.

But maybe I'm just overly jaded ;)

[rrrutledge]

The process by which the Host team interacts in prioritizing, reviewing, or changing the project is the same process that any interested Contributor could do.

I think the key word here is could, not that off-team contributors often (or ever) would do so. I think open means that host team members follow open rules that anyone on or off the team could do.

[lenucksi]

This is solid and good work. I've added a few minor comments.

[lenucksi]

I don't entirely catch what this sentence is supposed to purvey. Can this be formulated differently?

[lenucksi]

@rrrutledge What I did not get here (and probably turned into a sentence that sounded much more harsh than what was intended) was the reference to 'tribal knowledge'. I was wondering if that could be phrased differently.
What would an example of tribal knowledge being created be here? What makes it tribal and how does that differ from common knowledge?

[breakbottle]

@lenucksi "Tribal knowledge" typically leans towards the core team overall knowledge of the project code and direction that may not be "common knowledge" for those outside of the core team. I totally get it but it probably should be written in a way that anyone reading the principles should understand without question.

Suggested change

	When possible, the above should be communicated in such a way that does lend itself to tribal knowledge.
	When possible, the above should be communicated clearly and in details, from teams internal definitions of items to special case scenarios specific to the project, in a manner that can be easily understood to those that are not part of the core team.

[lenucksi]

Sounds more understandable to me. I turned the suggestion in your comment into a commit suggestion.
I know the terms 'tacit knowledge' or 'implicit knowledge' for something describing similar concepts I guess - would those resemble what you wrote?

[lenucksi]

What does system refer to here? The technical artifacts of the project, the team's processes or the entire socio-technical construct that the inner source project in question is?

[rrrutledge]

technical artifacts of the project was what I was imagining.

[lenucksi]

How about adding software system to make this clearer then?

Suggested change

	In the process of doing so, they come to better understand the host team system as a general consumer.
	In the process of doing so, they come to better understand the host teams' software system as a general consumer.

Suggested change

	In the process of doing so, they come to better understand the host team system as a general consumer.
	In the process of doing so, they come to better understand the host teams' software product as a general consumer.

[lenucksi]

Looks like a typo to me.

Suggested change

	At times at may be a culture change for engineers on the host team to spend time helping others to code rather than just coding themselves.
	At times it may be a culture change for engineers on the host team to spend time helping others to code rather than just coding themselves.

[lenucksi]

I don't know exactly where this belongs, but I feel like in the end if a project is open and transparent then there becomes less and less difference between the way the Host team members interact with the project and the way that any Contributor interacts with the project. The process by which the Host team interacts in prioritizing, reviewing, or changing the project is the same process that any interested Contributor could do.

That is a valid observation and likely revolves around matters of project governance, project borders and the likes, one of @maxcapraro's papers has a categorization on this (and is worth having a look anyway).

That's not a specific suggestion, but wondering what you all thought about incorporating that ethos into some of what's been written, here?

While I think such issues are worth presenting and addressing, it might be a case of a 102 / more advanced topic. Maybe we can hint that such a continuum exist somehow. I have no clear sentence in mind right now, though.

[rrrutledge]

it might be a case of a 102 / more advanced topic

That makes sense - agreed.

[lenucksi]

Went through the PR and commented threads that I may have left open. It appears to me that we should be able to go through them, process them and then come to a point allowing us to merge the result.

I guess @rrrutledge, @demianbrecht and @KathrynKLewis would be the relevant involved persons here to have a look at the open threads in this PR.

[breakbottle]

@demianbrecht team wanted to know if this is ready for merging and if your too busy I can help move this forward.

Clint

[rrrutledge]

@breakbottle I caught up with @demianbrecht in Slack the other week and he mentioned that it sounds good for you to help move this forward!

[breakbottle]

@rrrutledge How can I get control to accept or make changes? I assume that is what you wanted me to do?

[breakbottle]

@lenucksi "Tribal knowledge" typically leans towards the core team overall knowledge of the project code and direction that may not be "common knowledge" for those outside of the core team. I totally get it but it probably should be written in a way that anyone reading the principles should understand without question.

Suggested change

	When possible, the above should be communicated in such a way that does lend itself to tribal knowledge.
	When possible, the above should be communicated clearly and in details, from teams internal definitions of items to special case scenarios specific to the project, in a manner that can be easily understood to those that are not part of the core team.

[rrrutledge]

@rrrutledge How can I get control to accept or make changes?

Good question. In the GitHub UI there is a button that will let you edit the files in the pull request. After editing you can open a new pull request to master and then we can close this one.

[lenucksi]

I think it might also be a way to resolve all the comments here along with commit suggestions, merge the entire PR (or have it merged depending on the permissions situation) and then do additional work on a new PR?

[breakbottle]

@lenucksi I like this idea, sounds like the quickest way to get things moving along, what is the way?

[rrrutledge]

Sounds good to me.

[lenucksi]

@breakbottle If you have a "Resolve conversation" button, click it on the conversations that are still open such that they are closed. If not, mark them with a comment and I will close them. If you see any need for changes, add a commit suggestion and we'll then see to get that merged in.
If everything's closed, either you (if you can) or someone else can go and click the big green "merge" button, merging everything in.

[breakbottle]

@lenucksi I do not have 'write access' therefore I do not have the buttons. I approved the pull request I believe others will need to as well. For this to move forward.

[lenucksi]

Good to see this merged. Here are a few nits though.

• I'd be good to take in the commit suggestions onto the next iteration of the PR, at least the one that fixes a typo (read: integrate them, they looked mostly undisputed or resolve their discussion shortly)
  • I will PR them onto the principles article
• The principles article currently does not have a number in front of it that we currently use to suggest an order for the articles. Do we want it to have one?

[rrrutledge]

The principles article currently does not have a number in front of it that we currently use to suggest an order for the articles. Do we want it to have one?

This isn't documented anywhere but in the past we had added the number once we were "finished" with the article. Although now that I think about it we should just look at the project board for status instead. So sure, number sounds good and reasonable to me.