ddeboer
commented
2 years ago I propose we call these top-level entities 'CLARIAH epics'
Agreed! ‘Epic’ emphasises the user’s perspective; moreover, it’s the level above ‘user story’, which makes sense in our case because the epics template contains user stories.
we can deepen the tree as far as we need…
True, but I advise to keep things as simple as possible.
We've been working in the Shared Development Roadmap for a while now and @roelandordelman suggested during the last TC meeting that we eventually move to a new "phase 2" document as we are progressing iteratively. We are moving from doing inventory to planning core shared 'services' that are at the heart of the shared development roadmap. He also suggested we use a common platform for our issues and project planning, we eventually settled on Github Projects as an acceptable solution.
In discussions with Roeland and Thomas I proposed that if we move to a phase 2 document; we move to a more formal structure that also aligns better with our choice of planning tools and issue trackers. We now have this central git repository (rather than a dozen different ones) as a store for all our 'meta' documents/issues for CLARIAH+. Developing the next phase of the Shared Development Roadmap in git, following a strict Markdown template makes sense to integrate with our planning tools. Eventually we would like to store individual components and their relations in a database (like Baserow), but this can then be a largely automatic extraction.
I see that our current data model for the current phase 1 Shared Development Roadmap leads to some confusion. I think this is due to our abstract notion of a 'CLARIAH+ Service' which does not correspond to a service in a technical sense (@ddeboer also remarked this in a comment). We keep having discussions on "is it a service or a component" and I found it hard to come to a model that best fits all our current inventory as well as our future plans.
In this pull request I made an attempt to reformulate the data model:
And I propose up a new template in Markdown, based on Roeland's phase 2 template:
The main change in the model is the following: What we used to call 'CLARIAH Services' were more like a collection of various closely related user stories from a scholarly perspective. The perspective and the needs of the scholarly user are central here, and that determines what actual services CLARIAH as a whole offers. Whether they are implemented as one or multiple services in a technical sense is not important from the user-perspective. That matters primarily from perspective as infrastructure developers and providers. We need a very clear view on the actual technical services and how they interrelate, and a clear view on the needs and requirements from the user. I propose we call these top-level entities 'CLARIAH epics' instead. They are epic-stories (defined by multiple underlying user stories) and we wanted to move in the direction of epics for our planning anyway. (I don't pretend to be an expert in 'agile' terminology so correct me if I'm very wrong, I'd say the term fits closely enough). These epics express general and non-implementation-specific needs by users. The epics in turn link to 'components' that, either together or in various subsets, provide an implementation for the stories expressed in the epic.
The second main change relates to various components; software components, service instances, data components, interoperability standards. Expressing these in flat tables like in the current SDR led to some confusion because these component relations are by definition hierarchical relations and can be nested quite deeply (if you'd recursively collect all your software dependencies as components, you'd get quite a deep tree). A tree structure with less restrictions on what can be a component of what feels more fitting and flexible, so in our Markdown template I'm simply using a bulleted list to express a tree structure. It may be less pretty than the colorful tables we had, but we can deepen the tree as far as we need for a full understanding of a particular service, and can insert any additional information we need at the appropriate level.
The shared document document as a whole can be turned into a PDF (
make shared-development-roadmap.pdf), uses GNU make and pandoc. An example of the resulting PDF is included in the repository.@roelandordelman , @tvermaut and anyone else who has an opinion: what do you think of this?