Embedding the guidelines of contribution to the radar items

[sakirtemel]

Hi!

Following up this issue: #97 (comment) @bocytko

I'd like to suggest this repository to have a place where the guidelines in blog post are written inside the repository. So, this repo can be more than a visualization library and become some sort of a lightweight framework for the organizations to adopt. ( for example MADR has great guidelines how to quickly adapt to the ADRs https://adr.github.io/madr/#applying-madr-to-your-project )

I suggest following changes and would start working on them if it's initially agreed.

1- Move the index.html and stuff out from docs and have them under starter-kit or example. This starter-kit is something that any organization can easily clone and aplly immediately to their organization.
2- Have github templates that are written in the blog post will be included somehow under it.
3- Have the each entry in entries saved as a asciidoc and have a compiler that goes through all the asciidocs and read the metadata from them ( https://docs.asciidoctor.org/asciidoc/latest/document/metadata/ )
4- Have a linter for these asciidocs, so they'd all look like the way it's in the blog post (includes pros, cons, when to use etc)
5- Have extensive guideline docs for how to contribute by having some diagrams, writing the roles, procedures etc
6- Have a script to have a monthly change report

So, what do you think? These are some initial thoughts that can enable and accelerate many organizations, later, the further imporvements can be done.

Waiting for your thoughts to start on that

[bocytko]

Thanks for the question @sakirtemel. This repository provides a library for technology choice visualization in the form of a tech radar. By forking the repository, organizations have easy means to make their technology choices publicly available.

Internally, we have a mkdocs-based site that contains individual entries per technology and uses the tech radar JS for visualization. We have an overview page per quadrant and visualize each quadrant using the zoom feature. Using the metadata from the markdown front matter we generate: (i) change logs for each entry, (ii) JSON datasets for easy integration in other tooling.
After the long weekend, I could discuss with my peers if we'd be willing to publish the skeleton of such a mkdocs-based documentation site (most likely in a separate repository). I can see how this can help others kickstart organizing their own knowledge base.

The process side of the tech radar is something that each organization has to decide upon on their own.
The blog posts we published on the Tech Radar shared highlights how we dealt with some key aspects of this process at Zalando.

[sakirtemel]

Thank you for the answer @bocytko , looking forward to the discussion result.

I did a similar skeleton and ready to share for your opinions if you decide to proceed. Used asciidoc instead markdown, as I thought they don't support metadata?

The process side of the tech radar is something that each organization has to decide upon on their own.

Definitely, however it'll be really beneficial for many organizations to kick start

-- entries
--- react.adoc
--- kafka.adoc
-- index.html
-- generateEntries.js
-- generated-radar-entries.json
-- radar-config.js
-- tech-radar.adoc

[SoumayaMauthoorMOJ]

@sakirtemel I'm using GitHub discussions instead of Markdown in our tech radar , with a discussion per entry, the discussion category to represent the technolofy category, and a label to represent the ring assignment. This means that people can add comments, reactions etc... I can then extract the GitHub discussions to the config.json using the GitHub graphql api. I've started working on that in the discussions folder. I would like to turn them into GitHub actions to make them reusable.