Add existing guidelines to qiskit docs guidelines

[HuangJunye]

Summary

We have written documentation guidelines in Box notes. This PR migrate those guidelines into .rst format within the new Qiskit Docs Guidelines sphinx project created by #108.

• Add tutorials guidelines
• Add how-to guide guidelines
• Add API reference guidelines
• Add explanation guidelines
• Simply internal cross-refernecing in toctree (see details below)
• Rename explanations to explanation

Fixes #81, Fixes #82, Fixes #83, Fixes #84.

This is a continuation of #100 which was closed because of branch renaming.

Details

This PR also simplifies the internal cross-referencing in toctree by putting the name of files instead of names with links. For example, previously we use:

.. toctree::

   Getting Started <getting_started>

now we use:

.. toctree::

   getting_started

The linked text is extracted from the title of getting_started file which is the same Getting Started. But using this new way we simply the cross referencing and avoid extra work on making sure the text Getting Started inside toctree matches the title of the linked page.

Details

[Guillermo-Mijares-Vilarino]

The code is cleaner this way! Nice detail.

Not sure about changing "explanations" to "explanation". I saw explanations as countable in the same way as tutorials, that is, each file is "an explanation".

However, now that I check the Diataxis page, explanation is used as uncountable there.

The word "explanation" can be used as both countable and uncountable so I guess it's a matter of choosing one and sticking to it.

[Guillermo-Mijares-Vilarino]

Might be better to separate a bit more the different points for readability.

Something like:

Lower the barrier of entry as much as possible. Assume the user does not know much about what is
covered in the tutorial.

If we are expecting users to know something, make it explicit and link them
to the needed explanations (See :ref:tutorial-guidelines-minimum-explanation)

Avoid jargon as much as possible. Provide a minimum
necessary explanation when the jargon is introduced. (See :ref:tutorial-guidelines-minimum-explanation)

[javabster]

This is looking great! I left some comments, mostly just grammar/typos.

Also a couple of general things:

• I think the numbered headings are too large when they actually get built, maybe you could use a different underline to make sphinx give it a smaller font size?
• When i build locally there seems to be some weird stuff happening with the toc tree, all your changes seem to be under API Reference, and nothing is showing under How-to-guides etc (screenshots attached)

[javabster]

I think it would be good to add a sentence or 2 at the top of this page to introduce what is going to be covered and when users should use this

[javabster]

For example something like: "This section provides guidelines for writing API References. This could apply to individual class or function pages, as well as module level pages ..."

[javabster]

I think it would also be good to reference our internal guidelines for docstrings, which follows the google spec i think

[javabster]

Show where? do you mean in the examples on the API reference? Or the actual docstring? They need to list all arguments in the docstring otherwise lint will fail. A bit more clarity in this section would be great

[Guillermo-Mijares-Vilarino]

This API guidelines are only about code examples. Maybe we should clarify that 😅

[javabster]

this reads like a note, i think it should be a full sentence. Also explain what CI is otherwise we aren't practicing what we preach about jargon haha

[Guillermo-Mijares-Vilarino]

These guidelines are supposed to be mainly for the mantainers of a Qiskit package. I think it's fair to assume they know what CI is. Also don't forget that this is not supposed to be a tutorial (so jargon is not so big a problem) but I can add an explanation about CI. What do you think? @javabster @HuangJunye

[javabster]

yeah most of the time i think it's fine to assume that, it's just that i was reading this straight after the section when you talk about not using jargon etc. and it just felt a bit hypocritical 😅

[javabster]

i wouldn't block merging on this bc of the acronym, just a suggestion. I do think it should be a full sentence though, and generally i think we should keep the grammar consistent in the page. so either all short note form or all full sentences, not a mix of both

[Guillermo-Mijares-Vilarino]

When i build locally there seems to be some weird stuff happening with the toc tree, all your changes seem to be under API Reference, and nothing is showing under How-to-guides etc (screenshots attached)

This is done on purpose. The guidelines, examples and templates themselves are our "API Reference" but each one is about tutorials, how-tos, reference or explanation, so you can see the how-to section as "the part of the docs/guidelines API reference that is about creating how-tos".

It's a bit confusing but it makes sense

[javabster]

When i build locally there seems to be some weird stuff happening with the toc tree, all your changes seem to be under API Reference, and nothing is showing under How-to-guides etc (screenshots attached)

This is done on purpose. The guidelines, examples and templates themselves are our "API Reference" but each one is about tutorials, how-tos, reference or explanation, so you can see the how-to section as "the part of the docs/guidelines API reference that is about creating how-tos".

It's a bit confusing but it makes sense

I don't think this makes sense tbh 😅 I think it would be better for readers to have each guideline live in the page associated with what the guidelines are about. So tutorial guidelines under the tutorials section, explanation guidelines under the explanation section etc.. Also our docs aren't an API so it's not correct for us to say that the guidelines form the API Reference, there is no API that we are referencing

[Guillermo-Mijares-Vilarino]

I don't think this makes sense tbh 😅 I think it would be better for readers to have each guideline live in the page associated with what the guidelines are about. So tutorial guidelines under the tutorials section, explanation guidelines under the explanation section etc.. Also our docs aren't an API so it's not correct for us to say that the guidelines form the API Reference, there is no API that we are referencing

Yeah we talked about the lack of actual API and agreed to rename "API Reference" to "Reference". The solution to this confusion (that we have in mind right now) is to add links from say the how-to page (with the actual how-to guides) to the Reference about how-to guides. Something like:

This section covers how-to guides for creating documentation, if you are looking for examples, templates or guidelines about writing how-to guides, check this reference material (link to how-to reference)

I believe putting say the how-to examples, templates and guidelines in the how-to section defeats the purpose of using Diataxis for docs_guidelines, as they are not how-to guides 😅

[javabster]

Honestly I don't really understand why we are using diataxis so strictly for the docs guidelines themselves 😅 I was assuming this is documentation to teach people how to use the diataxis framework in the context of Qiskit, and I don't think that necessitates implementing diataxis itself. Looking at https://diataxis.fr they keep info about writing tutorials under the tutorials page and info about api reference under the reference page etc etc. they don't put everything under reference and I don't think we should either. The guidelines aren't a piece of software so diataxis in this context just adds confusion for the user for the sake of showcasing diataxis, which I don't think is the best approach. Maybe we can discuss more in our next meeting, it's hard for me to get the full picture of your plans for the guidelines from individual PRs :)

[HuangJunye]

This PR is superseded by #166