feat: promote discover-your-innersource #780
Conversation
jeffabailey
requested review from
lenucksi,
NewMexicoKid,
cewilliams,
spier,
robtuley and
yuhattor
as code owners
fix: correct improve-findability.md link
…he file, as per the pattern template
There was a problem hiding this comment.
I pushed some changes to align the pattern with our pattern template.
Overall I think this is an interesting pattern, that has some way to go before being ready to be published to our book though.
My main concerns right now are:
- The Solution section contains multiple different things. What are the core aspects of the solution? Maybe we could try to group the bullets into categories, and give each category a distinct name to find out what the overarching themes of the solution are.
- How is this pattern related to other patterns like InnerSource Portal and Gig Marketplace?
- Not sure what to do with the "Discussion on" section. this seems more like meeting notes from a discussion that must have happened a long time ago. Maybe we can ask people that are still around if they remember anything about this pattern, like @gruetter and @NewMexicoKid
Besides that, we would have to check the requirements here before publishing to the book: Contributor Handbook - Requirements for maturity 'Structured'
If the ambition here is to have a better version of this pattern merged into our repo, I would recommend to leave this in the Initial state (and folder) for a bit longer. This would allow us to make some fixes and merge these PRs faster.
If the ambition is to get this pattern live in our book, then we will have to invest quite some work here and keep the PR open for a while.
Either way is fine with me, I just want to prevent frustrations as I don't know what your expectations are here.
|
Btw @jeffabailey if you want to use this pattern as a way to learn what it takes to get a pattern ready for publication in the book, by all means, keep pushing :) Just it might not be the easiest path on this particular pattern, as the current content of the pattern leaves a lot of room for improvement. |
spier
added
the
📖 Type - Content Work
Awesome, thank you!
This, TBH! :)
Sounds like a great challenge and learning opportunity. I'll read through more of the published patterns to align this one closer to the others. I was having a conversation with @rrrutledge about what constitutes an approachable and useful pattern. The patterns listed on the fearless change website are an interesting overlay to the patterns. https://fearlessjourney.info/fearless-change-patterns/ I really like "Discover Your InnerSource" name for the pattern. What do you think about the name?
Another great question to answer after defining the appropriate name and scope for this pattern. |
| ## Resulting Context | ||
|
|
||
| * Internal components are easily visible | ||
| * Developers looking for code can search for it and find it quickly. | ||
| * Developers are now looking internally for software components | ||
| * Search results are combined (internal and external) | ||
| * Process changes, establishing a common communications channel, and encouraging and rewarding owners of reusable code to use the same search engine can contribute to changing the corporate culture. Transformation begins from the grassroots but requires strategic involvement of thought leaders. | ||
| * See [Improved Findability](improve-findability.md) (aka Poor Naming Conventions or Badly Named Piles) as a related pattern. | ||
| * See [Improved Findability](../1-initial/improve-findability.md) (aka Poor Naming Conventions or Badly Named Piles) as a related pattern. |
There was a problem hiding this comment.
Yes, we would only link to same maturity or higher.
ie omit this link.
There was a problem hiding this comment.
Hmm - do we have a way to track the links that we remove from patterns as they move up so that those links can be added back as soon as the patterns one level further below move up as well?
There was a problem hiding this comment.
We can comment the link to keep the reference but not publish it.
Do we like this option?
There was a problem hiding this comment.
That sounds like a nice solution. I'm just trying to avoid losing these cross references.
There was a problem hiding this comment.
@jeffabailey feel free to try that approach with the commenting.
I have not used comments in markdown in this project, so we will have to try out if it works properly in gitbook as well (I suspect it will work though).
|
@jeffabailey I took some liberties and added the checklist for maturity Structured to the initial message of this PR. That gives us some guidelines for the various things that we want to check before promoting this pattern to our book. |
There was a problem hiding this comment.
The biggest challenge I see in this pattern at the moment is the Solution section.
- Some of the bullets in the Solution section propose things that already exist as dedicated patterns. We could link to them.
- Aside: this is not surprizing as some of those other patterns might have not existed 8 years ago when this pattern was drafted
- Through that we might also figure what is the "net new" content in this pattern.
- How is this pattern related to these patterns
I suspect my comments may seem overly critical of this pattern.
However my goal is to only publish useful patterns to the book. And given that this pattern has not been touched in so long, it will need a bit of love/work to be ready for prime time :)
| * Pull in repo names, descriptions and `README.md` files into the search engine assuming that a search engine exists. | ||
| * A one-stop-shop kind of search engine for all relevant communication and documentation is difficult to attain. | ||
| * Even when using GitHub's enterprise offering, people often deploy additional systems like wikis to host content orthogonal to what is in the code repositories, slack channels (or IRC), mailing lists (or even nntp servers), some place to store stuff written down in office formats, search over personal e-mail etc. | ||
| * Several of these systems come with search built-in, but integrating this content in one search box or even just deploying a federated search engine across all sources often doesn't come off-the-shelf. | ||
| * Implement process change to first check for internal solutions for this problem. | ||
| * Tool with a central view (but people are more inclined to google externally than look internally) |
| * Implement process change to first check for internal solutions for this problem. | ||
| * Tool with a central view (but people are more inclined to google externally than look internally) | ||
| * Concierge service (guide) to help product people find stuff. Might not scale but could be helpful in the beginning. | ||
| * Need some very visible lighthouse projects that start using inner source components and make positive statements about the inner source program. | ||
| * Establish a common, asynchronous communication channel (e.g., like slack or metamorph or yammer) across team boundaries. This might not scale beyond a certain organization size. It is possible people will start splitting this one channel into multiple channels by topic once traffic gets too high. Note: having one channel for many users of one tool might be considered an anti-pattern because they can't find it unless they already know about it. | ||
| * Need some very visible lighthouse projects that start using InnerSource components and make positive statements about the InnerSource program. |
There was a problem hiding this comment.
This seems unrelated to the problem at hand.
There was a problem hiding this comment.
I believe the failure to discover your InnerSource is described here as caused by two potential issues:
a) lack of a well integrated search engine for internal projects
b) people failing to even think of searching internally: "People don't bother looking for internally developed solutions" to quote the problem setting.
I would assume the positive examples talking about the benefits of InnerSource components addresses b)
Me personally I wouldn't call that lighthouse projects though - most likely because my gut feeling has a very negative co-notation with lighthouse projects. Instead One might talk about early adopters and link to the Crossing the Chasm pattern.
| * Need some very visible lighthouse projects that start using InnerSource components and make positive statements about the InnerSource program. | ||
| * Establish a common, asynchronous communication channel (e.g., like slack or metamorph or yammer) across team boundaries. | ||
| * This might not scale beyond a certain organization size. | ||
| * It is possible people will start splitting this one channel into multiple channels by topic once traffic gets too high. |
There was a problem hiding this comment.
| * It is possible people will start splitting this one channel into multiple channels by topic once traffic gets too high. | |
| * When using common chat systems, start with one single chat channel for the InnerSource project, only split into multiple channels by topic once traffic gets too high. This way the channel feels alive. In addition the number of input channels to watch is kept at a minimum for the host team. |
I think we need a bit of reasoning why one should start with only one communication channel. This might also link to our Communication Tooling pattern.
| * Establish a common, asynchronous communication channel (e.g., like slack or metamorph or yammer) across team boundaries. | ||
| * This might not scale beyond a certain organization size. | ||
| * It is possible people will start splitting this one channel into multiple channels by topic once traffic gets too high. | ||
| * Note: having one channel for many users of one tool might be considered an anti-pattern because they can't find it unless they already know about it. |
There was a problem hiding this comment.
I don't understand that sentence. Maybe instead mention where to mention this communication channel so that downstream users can find it? (E.g. withing the README.md of the project, the CONTRIBUTING.md of the project, ...?)
Co-authored-by: Isabel Drost-Fromm <[email protected]>
I agree this is a big challenge against this pattern. Following the style guide:
We might change this pattern's name to "Discover Internal Code" or "Discover Internal Projects" which does have sections that overlap Unified Source Code Inventory (USCI). I propose a rewrite to remove any overlapping concerns in USCI. My friend Cursor gave me this comparison: I'll help refine Overlapping Concepts to Remove:
Unique Aspects to Keep in discover-your-innersource.md:
Does this sound like a reasonable approach? |
…ailey/InnerSourcePatterns into pr/jeffabailey/780
|
@jeffabailey this comparison on the unique and overlapping concepts is very helpful! Could you also ask your friend Cursor for a comparison between this pattern and the InnerSource Portal pattern? My current take one the unique ideas in each of these patterns:
So maybe one could stay 1 and 2 are about tooling, while 3 is not? The idea of providing actual search functionality would fit equally well in 1 and 2, wouldn't it? Neither of these patterns has been very explicit about how to set up a good search engine with a focus on InnerSource though. My suspicion is that most orgs re-use the search functionality of their VCS (github, gitlab, ...) to accomplish this. Some might use Backstage. |
|
Sorry about the mess that I made with my last 3 commits. I was on the wrong branch. I cleaned it all up again (I hope), and committed those changes to #779 instead. |
Here's a comparison of concepts introduced in the three patterns using a custom GPT I created that sources our InnerSource Patterns and Managing InnerSource Projects book. 🧭 InnerSource Pattern Comparison Table
💡 Summary
Here's the prompt I used to produce this table.
That sounds reasonable. The table suggests that 3. is about culture and behavioral, and mindset changes. It seems the name of this pattern is moving toward "Promote Project Discovery" rather than "Discover Internal Code" or "Discover Internal Projects".
It depends on if we want to make this pattern about behavior, tooling, or both. |
|
This is really cool @jeffabailey . The comparison table with concepts, the 3 patterns, and the best-fit pattern is super helpful! I have various thoughts about different aspects of this. I will reply in separate comments, so that it becomes easier to separate the conversations. |
|
The way that you used AI support here is interesting. I have used ChatGPT for creating pattern drafts, but not for comparing patterns so yet.
I looked at your ChatGPT prompt. How did you add InnerSource Patterns and Managing InnerSource Projects book as sources thought? I cannot see how that works in the prompt. |
|
The comparison table is helpful for figuring out what the core focus of each of the existing patterns is, and how new patterns can add new insights to "fill the gaps" between the existing patterns. I wonder if such overviews/comparisons could be published as a new content type in our InnerSource patterns book (or elsewhere). If I had to give such write-ups a name I might call it "scenario", "use case", or even just "article". e.g. we could publish a scenario called "Enable project reuse". In that scenario we would incorporate the comparison table above, and point to patterns immediately related to the scenario (e.g. the 3 patterns that we are discussing here, and potentially others). I will post that idea as a new issue, so that it can be discussed separate from this PR here. |
I used using my ChatGPT account to create a custom GPT. 
Clicking on the innersourcecommons.org config at the bottom of this image, I added this schema. This uses https://innersourcecommons.org as a source. The other config is for api.github.com, which navigates the GitHub API to pull information. |
This pattern has been around in a draft/initial stage for a long time (almost 8 hears)!
As we believe that it does add some interest points, we want to try to improve it so that we feel comfortable publishing it in our pattern book.
Checklist
from the Contributor Handbook:
Extras
History