Show category+problem statement used in the mind map in the pattern as well

[spier]

This is a follow-up to the automation work done in #348 related to the pattern mind map.

Currently when a new pattern is written, the pattern author needs to add a reference of the new pattern to pattern-categorization/innersource-program-mind-map.md.

This has some disadvantages:

• easy to forget (because the patten author needs to change 2 files)
• the category and problem statement that is used in the mind map is not visible in the pattern itself i.e. there is no link from one place to the other

Solution idea

1. add the category+problem statement to the pattern MD file itself (that way it is already shown in the pattern)
2. write a script that consolidates the categories from all patterns/**/*.md files into innersource-program-mind-map.md
3. after that run the workflow implemented in #348 (would trigger automatically when (2) is done

[spier]

@fwan2000 it would be great to get your thoughts on both the problem description, as well as on the proposed solution or alternative solutions.

[fwan2000]

@spier I like the proposed solution. It would simplify the pattern discovery. For the category+problem statement in a pattern MD file, would the category be an existing node in the mindmap and the problem statement to be created to link the pattern to the node? For example, the trusted committee pattern would have two entries: "cultural challenges"+"unrecognized effort", "organizational challenges"+"not enough maintainers to scale". Does that match what you're thinking?

We may have more than one mindmap, e.g. another one for "how to tackle the obstacles for InnerSource". Shall we introduce a mindmap name beside the category+problem_statement entry?

It May also be worth adding a link to the mindmap in the patterns MD file to enable navigating both ways.

[spier]

@fwan2000 I haven't thought through how this would work technically. But let's toy with this.

We might have a new section called ## Category that we add to the pattern file. e.g. for the Trusted Committer pattern that category section might look like this:

Categories

• InnerSource Program
  • Adoption
  • Cultural Challenges
    • Unrecognized effort
  • Organizational Challenges
    • Not enough maintainers to scale

This would effectively list everything from the current innersource-program-mind-map.md file, except for the pattern title itself, as we are already looking at a single pattern, so it is clear which pattern we are categorizing.

By listing all levels in the category up to the root node "InnerSource Program", we would also enable ourselves to have more than one mindmap.

Writing a parser for this that extracts the categories and writes the innersource-program-mind-map.md would not be that hard. However if we wanted to validate what is a valid node in the category tree and what isn't, that would be harder (e.g. if we wanted to validate that the 2nd level needs to be one of Begin/Adoption/Grow/Scale). So I think we could just validate that type of thing manually for now, as part of the review process.

[fwan2000]

@spier Looks good to me. Maybe we could have a validation on the number of nodes in each level to detect any changes that add new non-leaf nodes? Then we can just manually validate those scenarios?

[spier]

I am thinking about the metadata structure for the implementation of the mindmap generator already. Probably solutioning too early but anyways :)

Pseudo mindmap.yaml below:

- innersource-program:
    name: InnerSource Program #human readable name/label for this mindmap
    filename-markdown: pattern-categorization/innersource-program-mind-map.md #write the categories extracted from the patterns to this file
    nodes: 4 #incl root without leave
    minimum-maturity: 2 #only show patterns of level 2 and 3 in this mindmap
- obstacles:
    name: Obstacles for InnerSource
    filename-markdown: pattern-categorization/innersource-obstacles.md
    nodes: 2
- program-project:
    name: Program or Project Pattern?
    filename-markdown: pattern-categorization/innersource-program-project.md
    nodes: 2