Update tutorial with new TOC

[GeorgLink]

In #93, we decided on a new table of content for the tutorial.

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

I expect that the TOC will evolve over time.

Initial work is in a branch 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)

Next steps is filling in the pages and creating a pull request to the master branch.

[GeorgLink]

Reminder: the goal is to build the tutorial around the Docker-Compose solution that is tested over at https://gitlab.com/Bitergia/lab/analytics-demo

#91 is the issue that kicked off the discussion for a new TOC to be able to integrate with the new docker-compose solution.

[valeriocos]

To speed up the next steps, it would be easier to work on the different sections by submitting PRs to the agamotto branch. Once the work is done, the agamotto branch should be merged to master.

I'm not sure about the goal you mention (which seems to fit only the quick start section). Other sections (e.g., architecture, dashbooard customization) are independent and can reuse part of the current tutorial.

[jsmanrique]

If it's planned to document that analytics-demo thing, wouldn't it make sense to make it part of chaoss/GrimoireLab somehow?

[valeriocos]

Some commits have been pushed to https://github.com/chaoss/grimoirelab-tutorial/tree/agamotto. They target the sections: Overview, Getting Started and Architecture.

After discussing with @jgbarah and @jsmanrique, it is probably needed to refine the TOC according to the type of target users. For instance, non-technical users could be interested in using just Cauldron, other users may be more confortable in using docker or docker-compose technologies to start with, other users may be focused on single components (e.g, Perceval, SortingHat, Graal).

Feel free to have a look at the new content and provide feedback, thanks

[canasdiaz]

@valeriocos I've been having a look at it and I think it is a good starting point. One comment, from my point of view this grimoirelab-tutorial should contain what we have at demo-analytics, or maybe what we need is to import a new CHAOSS project named grimoirelab-demo, so we can have the files we need there and add references to it from the tutorial.

What do u think folks?

[valeriocos]

I like the idea @sanacl ! +1

[jsmanrique]

@valeriocos I've been having a look at it and I think it is a good starting point. One comment, from my point of view this grimoirelab-tutorial should contain what we have at demo-analytics, or maybe what we need is to import a new CHAOSS project named grimoirelab-demo, so we can have the files we need there and add references to it from the tutorial.

What do u think folks?

-1. What you call analytics demo, should be part of chaoss/grimoirelab

Check chaoss/grimoirelab#220

[canasdiaz]

@valeriocos I've been having a look at it and I think it is a good starting point. One comment, from my point of view this grimoirelab-tutorial should contain what we have at demo-analytics, or maybe what we need is to import a new CHAOSS project named grimoirelab-demo, so we can have the files we need there and add references to it from the tutorial. What do u think folks?

-1. What you call analytics demo, should be part of chaoss/grimoirelab

This is why I wrote:

" or maybe what we need is to import a new CHAOSS project named grimoirelab-demo" ... because I think we should import that configuration files to any of the CHAOSS repos.

Check chaoss/grimoirelab#220

[GeorgLink]

I am undecided about creating a chaoss/grimoirelab-demo repo.

We have already a lot of repositories. It is a challenge to navigate that complexity and I'd rather not create a new repo. If we can include the necessary docker-compose file in the chaoss/grimoirelab repo, then that would be my preference. However, if the chaoss/grimoirelab repo is too big, then maybe having a separate repo makes more sense.

[jsmanrique]

Sorry, I don't get where this discussion is going.

To make clear my statement: -1 to add a new project or repo to GrimoireLab.

I think chaoss/grimoirelab should include every developed and documented way to install and run GrimoireLab toolkit as a whole platform approved by the community or the project.

[jsmanrique]

And about the tutorial discussion, I think we should write a new tutorial from scratch perhaps focus on GrimoireLab end users and let this one as it is or deprecate it in the future.

[jsmanrique]

Meanwhile, I've submitted a PR to update grimoirelab main repo: chaoss/grimoirelab#221

[GeorgLink]

I have no more travel until next year and would like to dedicate a few hours each week towards improving our tutorial. @valeriocos could we schedule a quick call to get me up to speed?

[valeriocos]

Sure! feel free to propose any time frame from 14h to 18h (Madrid time) for today, thanks

[valeriocos]

or maybe we can sync tomorrow. As you prefer.

[GeorgLink]

I didn't see your reply in time for today. I sent a calendar invite for tomorrow 2.30pm CET.

[vchrombie]

Hi I have seen a couple of discussions to improve the document which in fact is very necessary and we are continuously working on it. :+1: https://github.com/chaoss/grimoirelab/issues/135 https://github.com/chaoss/grimoirelab-sirmordred/issues/167

I just want to put up this program, Google Season of Docs which is just focused on technical writing. I was thinking if this could help.

Edit. I am sending some of the work done in the previous versions, https://developers.google.com/season-of-docs/docs/2019/participants.

[animeshk08]

I just want to put up this program, Google Season of Docs which is just focused on technical writing. I was thinking if this could help.

If this goes forward I would love to help :rocket:

[valeriocos]

Thank you @vchrombie and @animeshk08 for joining the discussion.

The Google Season of Docs could really help to make this issue advance. I see that the deadline is May 4, 2020 at 20:00 UTC , so there is still some time. @GeorgLink, do you think CHAOSS could apply for the program? Thanks

[GeorgLink]

Yes. We applied last year but weren't selected as one of the first 50 projects in the pilot of this new program. Can you initiate the conversation on the mailing list?

[vchrombie]

Can you initiate the conversation on the mailing list?

I'd like to volunteer for this. :slightly_smiling_face:

I couldn't attend the weekly meeting. I am curious to know if this was discussed over there. :thinking:

[valeriocos]

Hi @vchrombie , yes please send the email.

The last Grimoirelab weekly meeting was postponed, the next one will be on Apr 21st.

[vchrombie]

Hi @vchrombie , yes please send the email.

Sure.

The last Grimoirelab weekly meeting was postponed, the next one will be on Apr 21st.

I checked the minutes of the CHAOSS weekly meeting too. No problem, maybe we can add this point on the agenda for the next meeting. :slightly_smiling_face: Thanks.