Gazebo resources: Tutorials | Q&A | Documentation | Blog

GSoD 2020: Ignition Robotics on-boarding guide

Projects
,
#1

Hello Everyone!

I am Arnesh Kumar Issar, I come from India & am currently pursuing a Bachelors Degree in Chemical Engineering along with a Minor in Computer Science at Indian Institute of Technology, Kharagpur.

I was very happy to see that Julia has been selected for Google Season of Docs 2020 & would like to contribute more to the community through the program.

Specifically, what caught my attention is “ Ignition Robotics on-boarding guide ”. I have a pretty clear idea on where I would like to take this project,. But first let me share a few things about my background.

My Background

I am part of Autonomous Ground Vehicle, Kharagpur, a 40+ strong team of students consisting of skill expertise from Undergraduates to Research Scholars aimed towards building level 4 autonomy in vehicles. I am an AI & Software team member with Reinforcement Learning based approaches to Motion Planning.

Last year, our team participated in the 27th Intelligent Ground Vehicle Competition ( IGVC ) & bagged the runner’s up in the auto navigation course. My personal contribution was towards the lane detection & planning module which has given me insight into the technical aspects required for working with large scale teams & version control systems. Along with this I took the responsibility of compilation & editing of the design report that was submitted to the organizers.

I also provide advice to study.com as a computer science & math content reviewer where I provide feedback for the content written by authors spanning from various regions of the globe.

I would also like to add here my 5+ page documentation on a sampling based planner for Reinforcement Learning based application as an additional example of my technical writing work but unfortunately it is currently set confidential by AGV.

My Plans
For the GSoD 2020, I would like to revamp the contributing guide to the latest conventions along with introduction of software utilities for ease if contribution for less experienced users of ignition libraries.

A semi-detailed plan of some changes that I think would prove beneficial to the community are listed below in my google doc:

Google Doc

I have added the design report for IGVC,2019 in the doc to give you a practical idea of what I mean by my approach & the thought process behind doing things a certain way.

Doubts
I had some doubts when I was going through the present documentation & formulating a plan of action.

  • I wanted to know about the framework followed for the documentation so that I can familiarize myself with it. I am adept in Hugo, Jekyll & sphinx frameworks but have no reservations in working with any other frameworks as per need.

  • I would also like to enquire & discuss upon the doctests that are run for the code contributions made to the org.

I think this is a good overall introduction to my background, my work and my intentions regarding working with Flux to get the discussion going about the specific project that I would like to complete during this year’s Google Season of Docs program. I would highly appreciate your input, feedback, thoughts and comments.

I am looking forward to hearing from you!

#2

Hi Arnesh, thanks for showing interest in the program. Your proposal for an on-boarding guide has some great ideas. I’m a little unclear as to which project of ours you’re interested in, though. You mentioned Julia and Flux but we don’t have any products or projects with those names.

#3

Hey @marya!,

Well this is quite embarassing! It was an error on my behalf. Sorry for this show of unprofessional behavior.

I am interested to work on the on-boarding guide & would love to talk on the same.

I once again apologize for this behavior & look forward to the discussion.

#4

Hi Arnesh, it’s great to see that you already have some ideas about this project. The google doc sample shows a good direction.To answer your questions first:

We use Markdown for documentation.

We don’t have doctests for documentation yet, but do have a set of CI for code contribution. You don’t need to worry about test for this particular project.

A couple suggestions to draft a proposal: you could take a look at the contributing guide and think about potential improvements. Maybe ask yourself what you would like to know more about if you were a new ignition developer. To get a sense of style and layout, you could take a look at our current documentation.

It’d be helpful to see how to envision the on-boarding guide in your proposal and some work samples. We’d be happy to give feedback once if a draft is available!

#5

Thanks for the clarifications & suggestions. I’ll work upon them & add more details.

#6

@marya @claireyywang
I have made the script for creating github issues from google form using google script editor.

Form: https://forms.gle/wDcmrnxx3hZ1nVje7

The repo to which it creates issues (this can be changed to user input for various repos):

Kindly look upon this & suggest changes/imporvements for the same.

#7

@thefatbandit I just tried out your script, very nice work!

#8

@thefatbandit Your plan is great, as we’ve said, but at this point you should start focusing on refining your proposal. A few things to ask yourself could be how you envision the structure of the onboarding guide. Is it one continuous doc, or a series of docs covering different aspects of contributing? For example, your workflow section includes significant practical examples - do you think it makes sense for that to be a criteria for a section having its own page? Why or why not? Painting a picture of the overall structure of your project will help us better understand your vision.

Another thing you can take a deeper look into is your points about User Experience and Developer Experience. Evaluating the best use cases to address usually takes some in depth study of the wants and needs of the community. How are you planning on making decisions on what’s best for our community? Will you use existing resources? Analyze trends from our discourse and answers pages? Will you do some novel information gathering?

There’s no “right” answer to these questions, and you don’t even have to specifically address the questions I’ve suggested. I just want to encourage you to analyze the project from a technical writer’s point of view to help your application really stand out!

#9

@marya @claireyywang
I have worked upon your suggestions & made a preliminary structure for the guide.
Here is the LINK for the same.

@marya I have also prepared my initial project proposal in a formal document. I have mailed it to you on your osrf e-mail since I was not comfortable with putting it out in the community forum due to confidentiality of some of my previous work.