Do not duplicate end user, introductory knowledge in reference guide documentation
Introduction
There are several places in reference guides (and possibly other places) which introduces basic concepts in quantify (for example how to compile a schedule, how to use MeasurementControl
, what are the acquisition protocols, what's the acquisition data format, etc.). These information should be
- moved to the user guide, and
- should not be duplicated.
Examples
See for example
Task
Move every introductory documentation (what is quantify, what is a backend, how to create simple schedules, which operations exist on surface level, what is MeasurementControl
, how to compile simple schedules, how to write simple hardware configs, etc.) to user guide from reference guides.
Keep documentation which is relevant only for
- quantify developers,
- backend developers,
- debuggers, or
- power users at the reference guide.
Motivation
- It is a burden to maintain documentation if it is fragmented, and there is duplication. (If there mistakes in the introductory material, or new protocols, basic types are introduced or removed, we have to only fix it at one place.)
- The assumption is that everybody who is an advanced user/developer is already familiar with the basic concepts. For them, reintroducing things again is a distraction.
- Easier for end-users to get to know quantify: they never have to look at advanced sections. If material is duplicated, they might be confused whether it's for them or not.
History
We agreed with @slavoutich and @avarshiny that this documentation structure is desired, but unfortunately this is a bigger task. To not block !929 (merged) and !817 (merged), we decided to do this task in separate MRs.