Improving qcodes.github.io documentation
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 459
- Forks
- 359
- Avg merge
- 3d 6h
- Merged PRs (30d)
- 73
Description
When introducing new users to QCoDeS, I usually direct them to the [qcodes.github.io](qcodes.github.io\QCoDeS) documentation. However, I have noticed that people often have quite some remaining questions, and what I usually end up doing is performing a few measurements with them, explaining everything along the way.
I browsed through the documentation, and what I feel is missing most is a clear tutorial that explains exactly what a beginning user needs to know to perform his/her first measurement. There is `docs/examples/Tutorial.ipynb`, which does this to some extent, but it's located at the end of the documentation, and I believe it can use some improvements.
I was therefore thinking of rewriting the Tutorial. I think the target audience should be people who have freshly installed QCoDeS, and want to connect their instruments and perform their first measurement. I've listed my ideas for improving the Tutorial below, please comment if you want things added, or disagree with anything:
- Introduce how the tutorial is structured.
- Reference to other parts of documentation, such as `Parameter`, `Instrument` documentation/definition, other examples, etc.
This should be possible using nbsphinx. It will make it much easier for users to get more information.
- Shorten code for creating dummy instruments/parameters
I'm don't think it would be wise to move it entirely to a separate file, as I do see the appeal of introducing instruments and parameters this way. However, it's also a bit distracting, also because we're using mock instruments. I think it can be created easily using just an `Instrument`. A lot of the code can also be removed by using the features of the new `Parameter` class.
- Shorten `Basic instrument interaction`.
While it's good to mention that parameters have many properties, such as a step, I think actually showing examples of using these properties should be moved elsewhere, or at least be made more succinctly (no 40 print statements).
- Move more text to markdown cells, instead of comments.
It's more easily readable this way.
- Give short explanation of location provider, and data saving location, move up to after import
- Shorten `dac.snapshot()`.
While I think it's a good idea to mention that the metadata is stored, having an entire page of metadata is distracting. Not sure how to best improve this. Also it should be moved up to before the first loop.
- Add section for iPython for loop magic, noting that it's for iPython users only.
Our group now uses this by default, and it definitely makes a measurement more readable. I think it would be a good idea to mention this early on. Thoughts?
Additionally, I think a restructuring of the documentation would help. I propose the following changes:
- Change `Getting started` to `Setting up QCoDeS`
It doesn't contain information on actually getting started with measurements, which I think is good.
- Adding a tutorial as the next section (see above)
- Move `Get help` to last section, and mention that there is a tutorial + list of examples etc.
- Combine `User guide` and `Community guide`, make Contributing a separate section
- Move `Examples of using QCoDeS` up to below user guide, clean up TOC.
The TOC should be much more succinct. This will mean either reducing its max-depth, or changing the ipynb files in it. For sure the driver examples should have max-depth=1. Also move some examples to `Advanced examples`
I've also noticed a lot of overlap between the `User guide` (rst) and the examples (ipynb). I'm not sure what the best approach is here, as the user guide can be quite dry, especially without examples. Any thoughts?
@jenshnielsen @WilliamHPNielsen
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with docs/examples/Tutorial.ipynb and review the existing documentation structure, including Getting started, User guide, Community guide, and Examples of using QCoDeS. Use the listed tutorial and restructuring ideas as the scope; done would be an improved first-measurement tutorial with clearer references and a reorganized, more succinct documentation TOC.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- jupyter-notebook, python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100