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.
| ## 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.
Add Findability to vale, or use discoverability?
Recommend using discoverability if we keep this link in this PR.
There was a problem hiding this comment.
I would opt for "discoverability".
| * Comments may appear in the timeline but not with the file once it is edited (github)? | ||
| * https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/60 | ||
| * If only X knew what X knew; the internal search engine is bad. No one can find anything because it is difficult to add things to the search index. | ||
| * We have similar challenges getting data sources pulled into the search engine. PayPal is building a project called Agora to do this and they are planning to open source it. |
There was a problem hiding this comment.
@Danese is Agora a project at PayPal?
It looks like maybe yes? https://www.bis.org/about/bisih/topics/fmis/agora.htm
| * Don't bother looking | ||
| * Find it Inside | ||
|
|
||
| ## Discussion on |
There was a problem hiding this comment.
@spier move this discussion section here and link to it from this PR?
https://github.com/InnerSourceCommons/InnerSourcePatterns/discussions
There was a problem hiding this comment.
As these discussions are almost 8 years old, I doubt that they still have any traction. I would not create a new GitHub discussion for them.
Instead I would:
- port individual bullet points into other sections of this pattern if applicable.
- delete the rest
|
@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.
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