Melhorar a documentaçãoImproving Documentation

A documentação para o Kit de Desenvolvimento Quântico assume várias formas diferentes, de modo a que a informação esteja prontamente disponível para desenvolvedores quânticos.The documentation for the Quantum Development Kit takes on several different forms, such that information is readily available to quantum developers.

Seguindo os princípios de Docs como Código,toda a documentação do Kit de Desenvolvimento Quântico é formatada como código e é gerida usando o Git da mesma forma que o código fonte que é usado para construir o Kit de Desenvolvimento Quântico.Following the principles of Docs as Code, all Quantum Development Kit documentation is formatted as code and is managed using Git in the same way as the source code that is used to build the Quantum Development Kit. Na maior parte das vezes, a documentação de suporte de código consiste em várias formas de Markdown,um idioma para escrever texto ricamente formatado num formato de texto simples que é fácil de usar na linha de comando, em IDEs, e com controlo de origem.For the most part, the code backing documentation consists of various forms of Markdown, a language for writing out richly formatted text in a plain text format that's easy to use at the command line, in IDEs, and with source control. Também adotamos a biblioteca MathJax para permitir a formatação matemática em documentação usando a língua LaTeX, como detalhado mais abaixo.We similarly adopt the MathJax library to allow for formatting mathematics in documentation using the LaTeX language, as detailed further below.

Dito isto, cada forma de documentação varia um pouco nos detalhes:That said, each form of documentation does vary somewhat in the details:

  • A documentação conceptual consiste num conjunto de artigos que são publicados para https://docs.microsoft.com/quantum , e que descrevem tudo, desde os fundamentos da computação quântica até às especificações técnicas para formatos de intercâmbio.The conceptual documentation consists of a set of articles that are published to https://docs.microsoft.com/quantum, and that describe everything from the basics of quantum computing to the technical specifications for interchange formats. Estes artigos são escritos em DocFX-Flavored Markdown (DFM), uma variante de Markdown usada para criar conjuntos de documentação ricos.These articles are written in DocFX-Flavored Markdown (DFM), a Markdown variant used for creating rich documentation sets.
  • A referência API é um conjunto de páginas para cada Q# função, operação e tipo definido pelo utilizador, publicado para https://docs.microsoft.com/qsharp/api/ .The API reference is a set of pages for each Q# function, operation, and user-defined type, published to https://docs.microsoft.com/qsharp/api/. Estas páginas documentam as entradas e operações a cada chamada, juntamente com exemplos e links para mais informações.These pages document the inputs and operations to each callable, along with examples and links to more information. A referência API é extraída automaticamente a partir de pequenos documentos DFM em Q# código fonte como parte de cada libertação.The API reference is automatically extracted from small DFM documents in Q# source code as a part of each release.
  • Os ficheiros README .md incluídos em cada amostra e kata descrevem como usar essa amostra ou kata é usado, o que cobre e como se relaciona com o resto do Kit de Desenvolvimento Quântico.The README.md files included with each sample and kata describe how to use that sample or kata is used, what it covers, and how it relates to the rest of the Quantum Development Kit. Estes ficheiros são escritos usando GitHub Flavored Markdown (GFM), uma alternativa mais leve ao DFM que é popular para anexar documentação diretamente aos repositórios de código.These files are written using GitHub Flavored Markdown (GFM), a more lightweight alternative to DFM that's popular for attaching documentation directly to code repositories.

Contribuindo para a Documentação ConceptualContributing to the Conceptual Documentation

Para contribuir com uma melhoria da documentação conceptual ou README, começa então com um pedido de puxar para o MicrosoftDocs/quantum-docs-pr, Microsoft/Quantum,ou Microsoft/QuantumKatas,conforme apropriado.To contribute an improvement to the conceptual or README documentation, then, starts with a pull request onto either MicrosoftDocs/quantum-docs-pr, Microsoft/Quantum, or Microsoft/QuantumKatas, as is appropriate. Descreveremos mais sobre pedidos de puxar abaixo, mas por enquanto há algumas coisas que são boas a ter em mente à medida que melhora a documentação:We'll describe more about pull requests below, but for now there's a few things that are good to keep in mind as you improve documentation:

  • Os leitores vêm à documentação do Kit de Desenvolvimento Quântico de uma vasta gama de origens.Readers come to the Quantum Development Kit documentation from a very wide range of backgrounds. Todos os alunos do ensino secundário que procuram aprender algo novo e excitante até aos docentes que realizam pesquisas de computação quântica devem ser capazes de obter algo fora da leitura da documentação.Everyone from high school students looking to learn something new and exciting through to tenured faculty performing quantum computing research should be able to get something out of reading the documentation. Na medida do possível, por favor, não assuma um vasto conhecimento por parte dos seus leitores, pois podem estar apenas a começar. É muito útil se você pode fornecer descrições claras e acessíveis, ou pode fornecer links para outros recursos para mais informações.To the extent that's possible, please don't assume extensive knowledge on the part of your readers, as they may just be starting out. It's most helpful if you can provide clear and accessible descriptions, or can provide links to other resources for more information.
  • Os conjuntos de documentação não são definidos como livros ou papéis, na medida em que os leitores chegarão no que pode parecer o "meio".Documentation sets aren't laid out like books or papers, in that readers will arrive in what might seem like the "middle." Por exemplo, os motores de busca podem não sugerir o índice, ou podem ter sido enviados um link por um amigo tentando ajudá-los. Tente ajudar o seu leitor fornecendo sempre um contexto claro, juntamente com links sempre que apropriado.For example, search engines might not suggest the index, or they might have been sent a link by a friend trying to help them out. Try to help your reader by always providing a clear context, along with links where appropriate.
  • Alguns leitores acharão as declarações e definições abstratas mais úteis, enquanto outros leitores trabalham melhor extrapolando a partir de exemplos concretos.Some readers will find abstract statements and definitions most helpful, while other readers work best by extrapolating from concrete examples. Fornecer tanto o caso geral como exemplos específicos pode ajudar ambos os leitores a tirar o máximo partido da programação quântica.Providing both the general case and specific examples can help both readers get the most out of quantum programming.
  • Especialmente se também escreveu o código que está a ser documentado, as coisas podem ser óbvias para si que não são de todo óbvias para o seu leitor.Especially if you also wrote the code being documented, things may be obvious to you that are not at all obvious to your reader. Não há uma única maneira única de programar, por isso, por mais inteligente ou experiente que um leitor possa ser, eles não conseguem adivinhar quais os padrões de design que achou mais úteis para expressar as suas ideias em código.There's no one unique best way to program, so no matter how clever or experienced a reader might be, they can't guess at what design patterns you found the most helpful to express your ideas in code. Ser claro sobre como um leitor pode esperar fazer uso do seu código pode ajudar a fornecer esse contexto.Being clear about how a reader can expect to make use of your code can help provide that context.
  • Muitos membros da comunidade de programação quântica são investigadores académicos, e são reconhecidos principalmente através de citações pelas suas contribuições para a comunidade.Many members of the quantum programming community are academic researchers, and are recognized mainly through citations for their contributions to the community. Além de ajudar os leitores a encontrar materiais adicionais, certificar-se de citar corretamente saídas académicas como jornais, palestras, posts de blog e ferramentas de software pode ajudar os colaboradores académicos a continuarem a fazer o seu melhor trabalho para melhorar a comunidade.In addition to helping readers find additional materials, making sure to properly cite academic outputs such as papers, talks, blog posts, and software tools can help academic contributors to keep doing their best work to improve the community.
  • A comunidade de programação quântica é uma comunidade ampla e maravilhosamente diversificada.The quantum programming community is a broad and wonderfully diverse community. O uso de pronomes de género em exemplos de terceira pessoa (por exemplo: "se um utilizador..., ele...") pode trabalhar para excluir em vez de incluir.The use of gendered pronouns in third-person examples (e.g.: "if a user ..., he will ...") can work to exclude rather than include. Ser consciente dos nomes das pessoas em citações e ligações, e da correta inclusão de caracteres não ASCII pode servir a diversidade da comunidade mostrando respeito aos seus membros.Being cognizant of people's names in citations and links, and of the correct inclusion of non-ASCII characters can serve the diversity of the community by showing respect to its members. Da mesma forma, muitas palavras na língua inglesa são frequentemente usadas de forma odiosa, de modo que a sua utilização em documentação técnica pode causar danos tanto aos leitores individuais como à comunidade em geral.Similarly, many words in the English language are often used in a hateful manner, such that their use in technical documentation can cause harm both to individual readers and to the community at large.

Referência do Código da Amostra a partir de artigos conceptuaisReferencing Sample Code from Conceptual Articles

Se pretender incluir o código do repositório de amostras,pode fazê-lo utilizando um comando especial DocFX-Flavored Markdown:If you want to include code from the samples repository, you can do so using a special DocFX-Flavored Markdown command:

:::code language="qsharp" source="~/quantum/samples/algorithms/chsh-game/Game.qs" range="4-8":::

Este comando importará as linhas 4 a 8 Game.qs do ficheiro da chsh-game amostra,marcando-as como Q# código para efeitos de prostaxe.This command will import lines 4 to 8 of the Game.qs file from the chsh-game sample, marking them as Q# code for the purpose of syntax highlighting. Utilizando este comando, pode evitar duplicar o código entre os artigos conceptuais e o repositório de amostras, de modo que o código de amostra na documentação esteja sempre o mais atualizado possível.Using this command, you can avoid duplicating code between conceptual articles and the samples repository, so that sample code in documentation is always as up to date as possible.

Contribuindo para as Referências da APIContributing to the API References

Para contribuir com uma melhoria das referências da API, é mais útil abrir um pedido de puxar diretamente sobre o código que está a ser documentado.To contribute an improvement to the API references, it's most helpful to open a pull request directly on the code being documented. Cada função, operação ou tipo definido pelo utilizador suporta um comentário de documentação (denotado /// em vez de // ).Each function, operation, or user-defined type supports a documentation comment (denoted with /// instead of //). Quando compilamos cada lançamento do Kit de Desenvolvimento Quântico, estes comentários são usados para gerar a referência API em https://docs.microsoft.com/qsharp/api/ , incluindo detalhes sobre as entradas e saídas de cada chamada, os pressupostos que cada chamada faz, e exemplos de como usá-los.When we compile each release of the Quantum Development Kit, these comments are used to generate the API reference at https://docs.microsoft.com/qsharp/api/, including details about the inputs to and outputs from each callable, the assumptions each callable makes, and examples of how to use them.

Importante

Certifique-se de que não edita manualmente a documentação da API gerada, uma vez que estes ficheiros são substituídos a cada nova versão.Please make sure to not manually edit the generated API documentation, as these files are overwritten with each new release. Valorizamos a sua contribuição para a comunidade e queremos garantir que as suas alterações continuem a ajudar os utilizadores a lançar após o lançamento.We value your contribution to the community, and want to make sure that your changes continue to help users release after release.

Por exemplo, considere a função ControlledOnBitString<'T> (bits : Bool[], oracle : ('T => Unit is Adj + Ctl)) : ((Qubit[], 'T) => Unit is Adj + Ctl) .For example, consider the function ControlledOnBitString<'T> (bits : Bool[], oracle : ('T => Unit is Adj + Ctl)) : ((Qubit[], 'T) => Unit is Adj + Ctl). Um comentário de documentação deve ajudar um utilizador a aprender a interpretar bits e a qual é a oracle função.A documentation comment should help a user learn how to interpret bits and oracle and what the function is for. Cada uma destas diferentes informações pode ser fornecida ao Q# compilador por uma secção especialmente denominada Markdown no comentário da documentação.Each of these different pieces of information can be provided to the Q# compiler by a specially named Markdown section in the documentation comment. Para o exemplo ControlledOnBitString de, podemos escrever algo como:For the example of ControlledOnBitString, we might write something like the following:

 /// # Summary
 /// Returns a unitary operation that applies an oracle on the target register if the 
 /// control register state corresponds to a specified bit mask.
 ///
 /// # Description
 /// The output of this function is an operation that can be represented by a
 /// unitary transformation $U$ such that
 /// \begin{align}
 ///     U \ket{b_0 b_1 \cdots b_{n - 1}} \ket{\psi} = \ket{b_0 b_1 \cdots b_{n-1}} \otimes
 ///     \begin{cases}
 ///         V \ket{\psi} & \textrm{if} (b_0 b_1 \cdots b_{n - 1}) = \texttt{bits} \\\\
 ///         \ket{\psi} & \textrm{otherwise}
 ///     \end{cases},
 /// \end{align}
 /// where $V$ is a unitary transformation that represents the action of the
 /// `oracle` operation.
 ///
 /// # Input
 /// ## bits
 /// The bit string to control the given unitary operation on.
 /// ## oracle
 /// The unitary operation to be applied on the target register.
 ///
 /// # Output
 /// A unitary operation that applies `oracle` on the target register if the control 
 /// register state corresponds to the bit mask `bits`.
 ///
 /// # Remarks
 /// The length of `bits` and `controlRegister` must be equal.
 ///
 /// Given a Boolean array `bits` and a unitary operation `oracle`, the output of this function
 /// is an operation that performs the following steps:
 /// * apply an `X` operation to each qubit of the control register that corresponds to `false` 
 /// element of the `bits`;
 /// * apply `Controlled oracle` to the control and target registers;
 /// * apply an `X` operation to each qubit of the control register that corresponds to `false` 
 /// element of the `bits` again to return the control register to the original state.
 ///
 /// The output of the `Controlled` functor is a special case of `ControlledOnBitString` where `bits` is equal to `[true, ..., true]`.
 ///
 /// # Example
 /// The following code snippets are equivalent:
 /// ```qsharp
 /// (ControlledOnBitString(bits, oracle))(controlRegister, targetRegister);
 /// ```
 /// and
 /// ```qsharp
 /// within {
 ///     ApplyPauliFromBitString(PauliX, false, bits, controlRegister);
 /// } apply {
 ///     Controlled oracle(controlRegister, targetRegister);
 /// }
 /// ```
 ///
 /// The following code prepares a state $\frac{1}{2}(\ket{00} - \ket{01} + \ket{10} + \ket{11})$:
 /// ```qsharp
 /// using (register = Qubit[2]) {
 ///     ApplyToEach(H, register);
 ///     (ControlledOnBitString([false], Z))(register[0..0], register[1]);
 /// }
 /// ```
 function ControlledOnBitString<'T> (bits : Bool[], oracle : ('T => Unit is Adj + Ctl)) : ((Qubit[], 'T) => Unit is Adj + Ctl)
 {
     return ControlledOnBitStringImpl(bits, oracle, _, _);
 }

Pode ver a versão renderizada do código acima na documentação da API para a ControlledOnBitString função.You can see the rendered version of the code above in the API documentation for the ControlledOnBitString function.

Para além da prática geral da escrita de documentação, por escrito a documentação da API comenta que ajuda a ter algumas coisas em mente:In addition to the general practice of documentation writing, in writing API documentation comments it helps to keep a few things in mind:

  • O formato de cada comentário de documentação tem de corresponder ao que o Q# compilador espera que a sua documentação apareça corretamente.The format of each documentation comment has to match what the Q# compiler expects for your documentation to appear correctly. Algumas secções, tais como /// # Remarks permitir o conteúdo da forma livre, enquanto secções como a secção são mais /// # See Also restritivas.Some sections, such as /// # Remarks allow for freeform content, while sections such as /// # See Also section are more restrictive.
  • Um leitor pode ler a sua documentação da API no site de referência da API principal, no resumo de cada espaço de nome, ou mesmo dentro do seu IDE através da utilização de informações sobre hover.A reader may read your API documentation on the main API reference site, on the summary for each namespace, or even from within their IDE through the use of hover information. Certificar-se de que /// # Summary não é mais do que uma frase ajuda o leitor a resolver rapidamente se precisa de ler mais ou procurar em outro lugar, e pode ajudar a digitalizar rapidamente através de resumos de espaço de nome.Making sure that /// # Summary isn't longer than about a sentence helps your reader quickly sort out whether they need to read further or look elsewhere, and can help in quickly scanning through namespace summaries.
  • A sua documentação pode muito bem acabar por ser muito mais longa do que o código em si, mas tudo bem!Your documentation may well wind up being much longer than the code itself, but that's OK! Mesmo um pequeno pedaço de código pode ter efeitos inesperados para os utilizadores que não sabem o contexto em que esse código existe.Even a small piece of code can have unexpected effects to users that don't know the context in which that code exists. Ao fornecer exemplos concretos e explicações claras, pode ajudar os utilizadores a fazer o melhor uso do código que está disponível para eles.By providing concrete examples and clear explanations, you can help users make the best use of the code that's available to them.