Proposal for a new TOC for the tutorial

[canasdiaz]

In the ticket #91 @GeorgLink and I found an agreement about a TOC proposal for the tutorial. @jsmanrique just reminded me there are more proposals that should become publicly available, so we can discuss them with the community.

The aim of this ticket is to find an agreement about the new TOC for the tutorial. If the TOC is very different from what we have we can create a branch and work on it in parallel.

[canasdiaz]

This is the proposal A.

• Getting Started
  • Basic Concepts
  • Installation (installation using the docker containers)
  • Setting up your projects (with info about how to modify the setup.cfg and projects.json files)
    • GitHub
    • GitLab
    • ... one sub-page for each data source
  • Managing identities (explaining Sortinghat and Hatstall)
    • Hatstall
    • Sortinghat
  • Dashboards ( how to create visualizations and set up dashboards)
    • All data fields across all indexes
• Expert documentation
  • (focusing on installing GrimoireLab from scratch, using pip3)
  • ... this is where a lot of the current tutorial about the different components can go.

[GeorgLink]

If the TOC is very different from what we have we can create a branch and work on it in parallel

Is the idea to develop different TOC's in different branches?

[canasdiaz]

If the TOC is very different from what we have we can create a branch and work on it in parallel

Is the idea to develop different TOC's in different branches?

No, this is just an idea in case we want to see the evolution of the new document with new TOC. We can work with master and PRs and when we find the content is good enough to be published, we can make it publicly available at https://chaoss.github.io/grimoirelab-tutorial/

Does this answer your question @GeorgLink ?

[jsmanrique]

The proposal I had on mind is focus on:

• Start easy and fast to play with the platform
• Understand how the user can interact with each component

This is the TOC proposal:

• Quick start
  1. Download
  2. Define analysis scope:
  • Intro to projects.json
  • Intro to setup.cfg
  3. Deploy and run GrimoireLab
• GrimoireLab Architecture and Data Workflow
• Data Sources Management
  • The projects.json file: projects, data sources & repositories
  • Adding and removing projects, data sources & repositories
• Contributors information management
  • Identities and profiles
  • Merging, adding and removing identities to profiles
  • Editing profiles information: affiliation management
  • Adding and editing organizations information
• Dashboard and data visualization
  • Public and private access
  • Dashboard, panels and visualizations
  • Filtering, querying and searching
• Panels customization
  • Enriched indexes fields (name, type and description)
  • Editing existing panels
  • Creating new panels
  • Editing existing visualizations
  • Creating new visualizations
  • Adding visualizations to panels
  • Exporting and importing panels
• Customizing public dashboard
• Data Consumption through Elasticsearch REST API
• Platform management and monitoring

[canasdiaz]

I think your proposal may work @jsmanrique 👍

Any more feedback?

[GeorgLink]

Yes, @jsmanrique's proposal works just as well.

[canasdiaz]

Ok, this is the feedback we have for "proposal B":

• @jsmanrique 👍
• @GeorgLink 👍
• @sanacl 👍

Let's wait for a day or two to get more feedback. By Wednesday 09AM CDT we'll close the ticket if no more feedback is provided. If you think we should wait more please let me know.

"proposal B": #93 (comment)

[GeorgLink]

I posted to the CHAOSS mailing list about this issue. I think we can start working on this but we should give folks time to respond until after OSSNA. How about a week until August 26?

[valeriocos]

+1

[GeorgLink]

It looks like we are good to go. (lazy consensus achieved).

[valeriocos]

Good news, I can start working on it

[valeriocos]

A branch to work on the new tutorial is available at: https://github.com/chaoss/grimoirelab-tutorial/tree/agamotto

The TOC proposed above has been already set (https://github.com/chaoss/grimoirelab-tutorial/blob/agamotto/_data/sidebars/home_sidebar.yml)

I would close this issue and open other issues/PRs to advance on this task. WDYT?

[GeorgLink]

Thank you for getting the work started @valeriocos

Can we close the issue after merging the changes back to master? Because the work is not "done" from a user perspective before that time.

[valeriocos]

The aim of this issue was to define a proposal for a new TOC, so it could be closed since achieved its goal. However I agree with you that we need an issue to be closed after merging the changes back to master.

If you prefer to keep this issue open, we could update the description and title. Otherwise, we can open a new one to set up the next steps.

WDYT?

[GeorgLink]

Okay, I see your point about the purpose of the issue not being the implementation of the new TOC. Yes, I'm okay to close this issue and opening a new issue specific to updating the tutorial with the new TOC.

[valeriocos]

Great, feel free to close this issue and open a new one, thanks! :)

[GeorgLink]

done