qiskit-advocate/qamp-fall-22

Improve documention in Qiskit Machine Learning

Closed this issue · 9 comments

adekusar-drl commented

Description

In this project we will study Qiskit Machine Learning: explore the tutorials, try to run the algorithms available in the package, validate the documentation available on the web site and finally we'll try to find gaps in the existing documentation. The idea here is to re-read the documentation once a mentee is familiar with the topic and try to figure out what can be improved. Perhaps, in many cases a sample code snippet should be added to the documentation or default values should be explained better, etc. The work project can be split into small and easily consumable tasks.

Deliverables

A pull request and a few of them that improve the Qiskit Machine Learning documentation

Mentors details

  • Mentor 1
  • Name: Elena Peña Tapia
  • GitHub ID: @ElePT
  • What they do: Qiskit Applications developer

Number of mentees

1

Type of mentees

What is required:

  • Knowledge of quantum computing
  • Good knowledge of python and git
  • Good writing skills
ElePT commented

I can take over/collaborate in this project @adekusar-drl :)

  • 👍1
SanyaNanda commented

Hi, I am Sanya and I am interested in the project. I have intermediate understanding of quantum computing and qiskit, and wanted to start with QML, what better way than going through the documentation and working on it. I have good documentation skills as well.

SanyaNanda commented

Checkpoint 1

  1. #8
  2. Checkpoint 1 Slides: QAMP#8-Checkpoint1.pdf
  3. Video Presentation
  • ❤️1
SanyaNanda commented

Checkpoint 2

Progress:

Tutorial 1, 2, 2a and 5 have been improved as per the work methodology. The PRs for the same can be found in the comment above.

Work Methodology:

To enhance the documentation of Qiskit Machine Learning, the guidelines of the Divio/Diátaxis framework of documentation are being followed which categorises documentation in the following 4 blocks:

After thorough discussions, we classified the QML documentation to consist of tutorials (learning-oriented) and how-to guides (goal-oriented), both concerned with describing practical steps.

Tutorials are lessons that take the reader by the hand through a series of steps to complete a project. Tutorials are learning-oriented like teaching a child to cook: The important thing in this experience isn’t what you teach the child to cook. The only thing that really matters is that the child should enjoy the experience of working in the kitchen, gain confidence, and want to do it again. I have tried my level best to match this description of an effective tutorial.

Proposed Structure implemented:

The following structure has been implemented in the tutorials:

  1. Tutorial Title
  2. Overview: what is this tutorial about?
  3. Context/Introduction
  4. Main body of the tutorial
  5. Section by Section Summary
  6. What was learned?
  7. Qiskit copyright
  8. Qiskit version table

Some important pointers implemented in the tutorials for enhancing reader interactivity with content is as follows:

  • Get the user started by igniting their interest with the overview and providing a complete picture of what will be learned before they start. The overview is aligned with classical machine learning counterparts of quantum ways being introduced in the tutorial, so as to create relevance for the reader.
  • Whenever a new term is introduced, it is followed with a simple description and reference to the API documentation for more information, so as to not lose the big picture of the motive behind the tutorial.
  • There is an explanation before every cell of code with sufficient use of inline comments in the code for better understanding. Every cell’s output or result is shown immediately so that every step is clear and the reader gets visual cues.
  • Import statements in the first cell have been replaced by importing a library whenever required in the code from a logical perspective. Import when needed, Add Reference link of the function there, along with a one liner on what it does is the strategy being followed.

Work for the remaining sprint:

  1. Complete remaining tutorials by following the same process
  2. Inform the reader of the sometimes overlapping in the tutorial so that the reader is aware of the alternatives available to solve, say the problem of classification and the trade-offs that come along.
  3. Interconnections between the content will be put in the overview, so the user can easily navigate through tutorials knowing which tutorial may have prerequisites for another tutorial.
  • ❤️1
  • 🚀1
SanyaNanda commented

Pull Requests

PR4 (Tutorial 3): qiskit-community/qiskit-machine-learning#515 (MERGED)
PR5 (Tutorial 8): qiskit-community/qiskit-machine-learning#519
PR6 (Tutorial 7): qiskit-community/qiskit-machine-learning#522
PR7 (Tutorial 9): qiskit-community/qiskit-machine-learning#530
PR8 (Tutorial 1-redo): qiskit-community/qiskit-machine-learning#532 [due to merge conflict] (MERGED)
PR9 (Tutorial 5-redo): qiskit-community/qiskit-machine-learning#534 [due to merge conflict]

SanyaNanda commented

Supplementary Material

What I learned summarised as a road-map

General Template finalised by my mentor, @ElePT

GemmaDawson commented

Congratulations on completing all the requirements for QAMP Fall 2022!! 🌟🌟🌟