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.

Sign up for GitHub

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

Jump to bottom

Organizing documentation #135

Open
jgbarah opened this issue Jul 22, 2018 · 16 comments
Open

Organizing documentation #135

jgbarah opened this issue Jul 22, 2018 · 16 comments
Assignees
@jgbarah
Labels
help wanted

Comments

@jgbarah
Copy link
Contributor

jgbarah commented Jul 22, 2018

This issue was triggered by the insightful comments by @filmaj in chaoss/grimoirelab-sirmordred#167

To summarize, now we have the following documentation:

  • Some README.md files in source code repos, including some in subdirectories of them.
  • Some automatically built documentation from source code comments. In some cases (well, in one case) it is available in readthedocs: Perceval documentation
  • The Grimoirelab Tutorial, produced automatically from md files in docs dir in this repo.
  • Some interesting information here and there in some issues.

I agree with @filmaj that we should better organize it. In principle, the idea (I think) was:

  • README files for stuff like how to configure and run, how to contribute (maybe in separate CONTRIBUTING files), how to run tests and do other development-related stuff, and links to further documentation. In short, this would be information mainly for developers, and for letting users know the very basics, and where to find more. I would say this would be a kind of a reference manual for users, and in part (except for everything in the next item) for developers.
  • Automatically generated documentation from comments in the source code. This should be for the rest of developer-related information, including definition of the APIs, for example.
  • Tutorial. This was intended not as a reference manual, but as a tutorial of how to get stuff done. This should be the second thing a user would consult, after the README files that would explain the very basics, and after the detailed user guides that would be also a part of those README.

What do you (anyone reading this issue) think about this organization? Is still a sensible schema? (I'm not saying it is implemented this way now, just checking whether you find it convenient to set it as a goal).
@jgbarah jgbarah self-assigned this Jul 22, 2018
@filmaj
Copy link

filmaj commented Jul 23, 2018

All of that sounds great! I would support that.

The tutorial would arguably be one of the first things a new (potential) user would read. A reasonable new-user journey would be: land on the grimoirelab page and then very quickly click on "Docs" to land on the tutorial. From that perspective, perhaps it could use a review to make it gentler and aimed at users with little understanding of the architecture.

The READMEs in each repo could therefore be a bit more developer-centric, and more detailed with respect to the particular project. I think reviewing each repo's README (some have multiple, embedded in subdirectories!) from that angle would be helpful as well. I fully support adding a CONTRIBUTING.md file. Worth noting that how GitHub displays this file is different from READMEs: GitHub highlights this file when people file issues or are creating pull requests (and calls it out even more for a person filing issues/PRs for the first time). With that in mind, I think a CONTRIBUTING.md could be written up to include instructions directed at the contributor: what do they have to do or consider before filing an issue or sending a pull request? Do they need to sign a CLA? Hint to search the issue tracker first for an existing issue? Does the pull request have a related issue filed? Worth considering that each repo can have its own README / CONTRIBUTING and even issue and pull request templates, and each one could contain information that is more relevant to that particular repo.

Finally, the automatically-generated API references, I think, would be very helpful, especially if those are generated from comments within the code, or code itself, directly.

I am happy to help with any of these efforts! I am, however, still learning the project, so could use some direction :)

@MalloZup
Copy link

MalloZup commented Aug 31, 2018 •
edited
Loading

i will create some notes for setting up grimoireLab https://github.com/MalloZup/luce-on-grimoirelab

@jgbarah If you find any utility feel free to take/copy them, atm there will be only notes for me to remember how the setup and mechanism etc works. 🌻
I just post them here so you can have a feedback if you are interested otherwise for me are usefull 🍡

@MalloZup
Copy link

MalloZup commented Sep 3, 2018 •
edited
Loading

small feedback #144 on elastic-search.

Globally and in answer with this issue, i have the same opinion as @jgbarah but only one concern as i am a newbie now the grimoirelab experience 😄

to me seems more comfortable to have a webpage (tutorial or official webpage) that have a global installation. ( just to really minimalist and easy like create your dashboard with 10 commands)

pip install grimoirelab is really nice shot to install quite everything. ( or also docker is ok)

Having a global webpage ( or central readme) that say the basic about grimoireab to get the dashboard is more helpfull and less painfull to go through every github repository ( which should happen later when user want more advanced infos). This can help afaik.

In github repository to me should be more documented the tool as single detailed one , so having the scope of the tool + developers infos for contributing + api

@Polaris000
Copy link

Polaris000 commented Jan 24, 2019 •
edited
Loading

As I have previously mentioned on the grimoirelab mailing list (and opened a pull request), the grimoirelab tutorial website also lacks a favicon image which should appear in a browser's tab when visiting the website.

@MonikaEve
Copy link

Hi,
I found Bitergia through LinkedIn, as I'm currently on the job hunt. I thought I could break the ice, by contributing to your open source project. Do you still need support with this issue?

@valeriocos
Copy link
Member

Hi @MonikaEve, thank you for your interest in GrimoireLab, and indeed you are more than welcome to contribute to it. If you want to get a glimpse of GrimoireLab, you can start with the tutorial. Feel free to have a look also to the GSoC ideas for this year [1] or to the GrimoireLab components [2]. If you enjoying reading, we have also a nice blog and some research papers [3] waiting for you. WRT to job hunt, probably @jgbarah , @sduenas and @jsmanrique can help you with this.

[1] GSoC ideas

[2] GrimoireLab components

[3] Research papers

@jsmanrique
Copy link
Contributor

Hi @MonikaEve! Thank you very much for your interest. We always need help with this ticket. Another project that might be interesting is GrimoireLab Hatstall, the web app that connects and manages SortingHat. Since we are adding creating a GraphQL API for SortingHat, there is a work in progress to create a React based UI for Hatstall ... Sadly, there is not much doc about that (CC @sduenas @dlumbrer )

@dlumbrer
Copy link
Contributor

Hi @MonikaEve! Thank you very much for your interest. We always need help with this ticket. Another project that might be interesting is GrimoireLab Hatstall, the web app that connects and manages SortingHat. Since we are adding creating a GraphQL API for SortingHat, there is a work in progress to create a React based UI for Hatstall ... Sadly, there is not much doc about that (CC @sduenas @dlumbrer )

Hi @MonikaEve!!, @jsmanrique is right. As he said, we are working on the development of a new React based web app, this app will have the same aim than the GrimoireLab Hatstall based on Django: provide a user interface in order to manage SortingHat, but now, using the new version of SorthingHat that is has a GraphQL API.

This is the repository where the project is being developed. There is no doc yet, the project is still "new", but as I said before, the aim of this new web app is the same that the old Django GrimoireLab Hatstall has, but using the new GraphQL API of Sortginhat, so we are including all the functionality that the old app has as the new GraphQL API is having more "queries/mutations" (the way that a GraphQL API is). Therefore, we need more improvements and development in this app, in terms of general layout and in terms of complete the functionality. We are using React because is a powerful library in order to build user interfaces and we are used to working with Kibana, also based (most of it) on React.js.

@MonikaEve
Copy link

MonikaEve commented Mar 27, 2019 via email

@MonikaEve
Copy link

MonikaEve commented Apr 4, 2019 via email

@sduenas
Copy link
Member

sduenas commented Apr 4, 2019

Hi @MonikaEve, first of all thanks for your help!

Although, SortingHat is one of our more stable pieces, the new version is not, so I'm not sure how helpful would be to start working there.
I suggest to start with Perceval. It's the most stable one and there are many people out there using it. It would be great to have really good documentation for newbies. There's some stuff written in the grimoirelab-tutorial but documentation talking only about Perceval would be idea.

Perceval is partially well documented in terms of API but we need something better for the different kind of users the tool has.

Anyway, I can help you with both if you need to understand how things work or something is not clear. I'll happy to do it.

@MonikaEve
Copy link

MonikaEve commented Apr 5, 2019 via email

@valeriocos
Copy link
Member

Sure @MonikaEve , @sduenas and myself will be happy to set up a call, just ping us when you are ready :)

@MonikaEve
Copy link

MonikaEve commented Apr 7, 2019 via email

@valeriocos
Copy link
Member

Thank you for letting us know, enjoy!

@GeorgLink
Copy link
Member

Possibly related issue: chaoss/grimoirelab-tutorial#93

@jsmanrique jsmanrique mentioned this issue Oct 14, 2019
Closed
@vchrombie vchrombie mentioned this issue Apr 10, 2020
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@jgbarah jgbarah

Labels
help wanted
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
10 participants
@filmaj @sduenas @jgbarah @jsmanrique @valeriocos @GeorgLink @dlumbrer @MalloZup @MonikaEve @Polaris000