InnerSource Glossary

[dellagustin]

https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/meta/glossary.md

[dellagustin]

Related discussion on Slack: https://innersourcecommons.slack.com/archives/C04DT6NQX7G/p1697455215800529

Shared by @spier : https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/meta/glossary.md

[dellagustin]

The existing glossary is part of the Patterns book, but I it does not seem to be part of the book itself.

[dellagustin]

The Learning Path has videos dedicated to roles, like Trusted Committer, that could make it to the Glossary.

[jeffabailey]

Justin: I would like to see more written down about how peoples' definitions of perspective on InnerSource can vary a lot between large & small companies and between definitions based on "behaviors and a "type" of project.

Justin says:So glossary and governance might be two places to put that somewhere

[jeffabailey]

@dellagustin @rrrutledge

Is there any reason we shouldn't publish an InnerSource glossary in the Managing InnerSource book?

@spier Does the glossary belong in the patterns?

Putting the glossary in the book may help ensure each section of the book uses the same meaning of common InnerSource terminology.

[spier]

@jeffabailey as you can tell within the patterns/repo book we only have an extremely small amount of glossary terms so far :) So from that perspective it does not really matter to me where the glossary lives.

I do think that maintaining a shared glossary would be great, so that we can use the terms consistently across all ISC resources!

Also in some of our existing books (e-books) we already have glossaries. So we could possibly start with those glossaries and expand them.

Technically we might even maintain the glossary in a central place. And then embed into the different ISC resources. Or link from the different ISC resources to the central term definitions. Whatever makes most sense :)

What is the motivation within the ISPO WG to create a glossary? From this issue here alone I cannot tell.

[rrrutledge]

I like the idea of the glossary in the “Managing” book.

[gvlx]

@jeffabailey as you can tell within the patterns/repo book we only have an extremely small amount of glossary terms so far :) So from that perspective it does not really matter to me where the glossary lives.

I do think that maintaining a shared glossary would be great, so that we can use the terms consistently across all ISC resources!

Also in some of our existing books (e-books) we already have glossaries. So we could possibly start with those glossaries and expand them.

Technically we might even maintain the glossary in a central place. And then embed into the different ISC resources. Or link from the different ISC resources to the central term definitions. Whatever makes most sense :)

What is the motivation within the ISPO WG to create a glossary? From this issue here alone I cannot tell.

Having one single glossary would help maintaining all definitions in sync across all document. It would also greatly help the work of the translators.

The remaining documents could just incorporate the current version of glossary at the time of the closing of the edition (when it receives the final tag).

[jeffabailey]

What is the motivation within the ISPO WG to create a glossary? From this issue here alone I cannot tell.

Putting the glossary in the book may help ensure each section of the book uses the same meaning of common InnerSource terminology.

[jeffabailey]

The remaining documents could just incorporate the current version of glossary at the time of the closing of the edition (when it receives the final tag).

Any recommendations on achieving this? Do we have other implementations of shared content incorporated in other documents?

@rrrutledge I recall us discussing how we might allow ISPOs to embed content in their internal projects, but I don't think we bottomed out on solution options.

[rrrutledge]

No - we need this, though. I feel like there should be a way for something like GitBook to take markdown from a remote location and include it in the deployed, static, site as easily as markdown on the local file system. It’s just my mental model, though - I haven’t looked at any technology to make it happen. Conceptually it makes sense, though.

[spier]

gitbook just reads markdown from the git repo that it is synced with.

Listed some options below. They only one that I am 100% confident that it would work is (1). If anybody has time to try any of the others, would be curious to hear about the results :)

(1) Pull in glossary via CD (e.g. GitHub Actions)

What should, would therefore be a CD step that always pulls in the latest version of the glossary into the main branch. As long as that then leads to a commit in the repo, gitbook will pick that up and deploy it.

(2) git submodules?

Maybe git submodules could work? I don't know if gitbook would be able to handle those

(3) random find but no idea what it means

https://docs.gitbook.com/content-creation/blocks/embed-a-url#git-sync-representation-in-markdown

[gvlx]

@spier, probably (1) would update (2) before proceeding.

[spier]

@spier, probably (1) would update (2) before proceeding.

Yeah, maybe they could be used in combination. However I am not sure if (2) even works with gitbook :)

We just have to try.

[claredillon]

Just adding a note on this from the discussion at the ISPO Working Group just now. The scenario was described about folks within an org having different definitions of project vs. repo (among other things) - if that lack of clarity happens within an org, it's magnified across the ISC.

So the motivation from the ISPO group as I see it is:

• Get clarity around certain terms that may have ambiguity depending on company context.
• Use the ISC glossary as a reference for internal glossaries / debates

"Trusted Commiter" was another term that was referenced as having multiple interpretations. One way of dealing with any divergences in definitions like this could be to have headings like like... always..., sometimes..., never... to help folks capture the essence, the divergence and the edge cases.

[spier]

"Trusted Commiter" was another term that was referenced as having multiple interpretations. One way of dealing with any divergences in definitions like this could be to have headings like like... always..., sometimes..., never... to help folks capture the essence, the divergence and the edge cases.

Can you share an example of how this might look like @claredillon ? I am unsure if I understood the always/sometimes part.