Re-organize the Data Science Section

[oindrillac]

The data science section currently consists of a lot of blogs and notebooks linked, and the vastness of the content is making it less discoverable and less welcoming for new contributors.

related https://github.com/aicoe-aiops/ocp-ci-analysis/issues/258

Acceptance:

• Come up with ideas and a plan to re-org the content

[oindrillac]

@isabelizimm suggested that each project will have 4 markdowns "Overview", "Getting Started", "How to Contribute", "Content". Roughly building up on that:

We will have project as a section on the left hand Panel except the "All Projects" document, which will be the first markdown on the left hand panel.

Each project can have 4 markdowns:

• Overview - A short (preferably < 250 words) overview of the project, which exclude any "how to get started"/"how to contribute" sections and focuses less on specific content/notebooks and more on the overarching goals and links project level video explainer. Good example is https://www.operate-first.cloud/data-science/cloud-price-analysis/

• Getting Started - This section encourages a new user to start "familiarizing" oneself with the project. This could mention the steps needed to spawn up a jupyterlab image/ access the repo/ run certain notebooks/watch a video etc.

• How to Contribute - This will be targeted towards users who are interested in contributing back and this talks about the process one should follow to open a template issue/ submit PRs etc. All projects may not be at a stage where it has a streamlined way to accept contributions except PRs and Issues. Those projects can have a markdown just stating "Open a PR/Submit an Issue to contribute" or even maybe linking "good first issues" etc or we can avoid this markdown too.

• Content - This content markdown stems from the idea that linking all the notebooks of a project from the left hand panel makes it pretty unorganized. So we can just remove all the individual notebooks from the left hand panel and rather link them from this "Content" markdown. Especially, for projects like AI4CI which have various "types" of content, this doc will be very helpful for segregating them into different headers with some description for each and linking them from there. Sort of how we are linking the different notebooks and blogs in the AI4CI Readme for each data source.

We can try this out with the AI4CI project by re-organizing our docs a little bit and putting them up on the site. We can come up with guidelines on the basis of that, which we can extend to our other projects.

WDYT?

[MichaelClifford]

@oindrillac @isabelizimm Sounds good.

For the "overview" section, we have been using the project readme to serve this purpose. Are you suggesting there be an additional abbreviated markdown in addition to the readme or the overview becomes the readme?

If its the former, how do you see the project readme functioning in this set up? Would it just link out to these other 4 documents?

[oindrillac]

@oindrillac @isabelizimm Sounds good.

For the "overview" section, we have been using the project readme to serve this purpose. Are you suggesting there be an additional abbreviated markdown in addition to the readme or the overview becomes the readme?

If its the former, how do you see the project readme functioning in this set up? Would it just link out to these other 4 documents?

yes, I like that idea of having a separate overview doc which is published on the site and the project readme just has a brief overview (<100 words) like given here and it links to the 4 individual documents.

what do you think?

[MichaelClifford]

@oindrillac sounds good :+1:

[isabelizimm]

Making sure I'm not getting lost in overview docs vs. overview pages vs. readme vs. documents in various places in the sidebar... :)

• One page to easily scroll through all the projects. The descriptions would be <100 words, which is the link @oindrillac gave. This is not the readme since it should be more brief. It could link to the project on the Operate First site and Github repo, and could also function as the landing page for the Data Science tab?

• Structured template for each individual project Proposed template is 1. Overview aka the repo's readme example, 2. Getting Started, 3. How to Contribute, 4. Content aka links to notebooks.

I'm hoping that answered @MichaelClifford and just reiterated @oindrillac point :)