Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update tutorial with new TOC #104

Open
GeorgLink opened this issue Sep 6, 2019 · 23 comments
Open

Update tutorial with new TOC #104

GeorgLink opened this issue Sep 6, 2019 · 23 comments

Comments

@GeorgLink
Copy link
Member

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
    1. 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
Copy link
Member Author

GeorgLink commented Sep 8, 2019

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
Copy link
Member

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
Copy link
Contributor

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

@valeriocos
Copy link
Member

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
Copy link

@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
Copy link
Member

I like the idea @sanacl ! +1

@jsmanrique
Copy link
Contributor

@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
Copy link

@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
Copy link
Member Author

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
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Contributor

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

@GeorgLink
Copy link
Member Author

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
Copy link
Member

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

@valeriocos
Copy link
Member

or maybe we can sync tomorrow. As you prefer.

@GeorgLink
Copy link
Member Author

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

@vchrombie
Copy link
Member

vchrombie commented Apr 10, 2020

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. 👍
chaoss/grimoirelab#135
chaoss/grimoirelab-sirmordred#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
Copy link
Contributor

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 🚀

@valeriocos
Copy link
Member

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
Copy link
Member Author

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
Copy link
Member

vchrombie commented Apr 14, 2020

Can you initiate the conversation on the mailing list?

I'd like to volunteer for this. 🙂

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

@valeriocos
Copy link
Member

Hi @vchrombie , yes please send the email.

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

@vchrombie
Copy link
Member

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. 🙂
Thanks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

6 participants