Repository navigation
Show category+problem statement used in the mind map in the pattern as well #349
Description
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. Here is more documentation of how the mindmap generation works.
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
- add the category+problem statement to the pattern MD file itself (that way it is already shown in the pattern)
- write a script that consolidates the categories from all
patterns/**/*.mdfiles intoinnersource-program-mind-map.md - after that run the workflow implemented in Generate mind map automatically (via GHA) #348 (would trigger automatically when (2) is done
Reacted by Manrique Lopez
Activity
spier commentedon Sep 1, 2021
@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 commentedon Sep 7, 2021
@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 commentedon Sep 8, 2021
@fwan2000 I haven't thought through how this would work technically.
But let's toy with this.
We might have a new section called
## Categorythat we add to the pattern file.e.g. for the Trusted Committer pattern that category section might look like this:
This would effectively list everything from the current
innersource-program-mind-map.mdfile, 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.mdwould 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 commentedon Sep 10, 2021
@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 commentedon Sep 10, 2021
I am thinking about the metadata structure for the implementation of the mindmap generator already.
Probably solutioning too early but anyways :)
Pseudo
mindmap.yamlbelow:spier commentedon Feb 4, 2025
Exploring further how one might store the data from the mindmap in the pattern markdown files, so that the data can be
a) correctly rendered into HTML
b) extracted and fed into the mindmap
Examples
For pattern "Start as an Experiment":
markdown:
Rendered:
For pattern "Trusted Committer":
Shows how this might work if the pattern should show up in multiple places in the mindmap.
markdown:
Rendered:
Thoughts
For this approach to work, we would need one centrally maintained base template file for the mindmap that contains the levels 0+1+2. That way we would not have to repeat the levels 0+1 in the pattern itself.
I am not sure how easy it would be for pattern authors to understand what they have to enter in the pattern in order for it to show up somewhere in the mindmap though :) Might be that still the maintainers of the ISC patterns repo have to help the pattern authors with this. Still, it would be easier for the maintainers as well.
For the current structure of the mindmap, the base template file would only contain the data show below: