Documentando uma linguagem de programação: Manual de Referência

Estamos procurando reformular a documentação em toda a nossa linha de produtos. Parte disso inclui manuais de referência para uma linguagem de programação usada como parte do sistema.

Ao escrever um manual de referência para uma linguagem de programação, qual é a melhor maneira de estruturá-lo para maximizar a usabilidade daqueles que são novos na linguagem?

Quais são os principais aspectos de cada palavra-chave documentada?

• Sintaxe
• Descrição
• Argumentos - se aplicável
• Valores de retorno - se aplicável
• Exemplo de uso?
• Falta algum outro?

Os conceitos (como estratégias de bloqueio, detalhes relacionados ao desempenho) também devem ser documentados neste manual de referência ou é um documento separado?

_{Isto é para consumo externo. Já temos conjuntos de documentos completos (consulte: http://www.rocketsoftware.com/u2/resources/technical-resources ). Descobrir o que devemos fazer de diferente - eu já tenho minhas idéias, mas como sempre, tento não confiar apenas na minha opinião.}

_{Público-alvo: desenvolvedores técnicos que usam nossos bancos de dados e ferramentas para produzir software em vários setores.}

Organize a documentação de acordo com as necessidades do público-alvo.

No seu caso, o público principal são aparentemente desenvolvedores de software. As partes a considerar aqui devem abordar diferentes "sub-audiências" desta:

1. Olá Mundo.
   Para aqueles que desejam experimentar rapidamente, basta criar e executar um aplicativo de amostra para ver como ele se parece.
   Pense no público como aquele abordado pelo MySQL "15 minutes rule" :
   

   _{... um usuário para poder ter o MySQL em funcionamento 15 minutos depois de terminar o download.}

2. Fundamentos.
   Para os caras dispostos a aprender rapidamente as coisas necessárias para começar a produzir software de trabalho.
3. Tópicos avançados.
   Para desenvolvedores já bem familiarizados e praticados com fundamentos, interessados ​​em saber o que há além. Tópicos principais que não foram abordados nos Fundamentos .
4. Guia de Estilo / Práticas Recomendadas.
   Aconselhamento e orientação subjetiva para os interessados ​​na maneira como você recomenda fazer as coisas.
   _{A pergunta não indica se isso poderia ter um público substancial no seu caso; portanto, as opções a serem consideradas são incluí-lo como parte / apêndice de tópicos avançados ou até mesmo descartá-lo completamente.}
5. Peculiaridades.
   Tópicos obscuros, fora do mainstream, que podem interessar uma fração bastante limitada do seu público. Por exemplo, se você tem uma linha herdada, ou coisas como atualização / migração / interoperabilidade com o herdado - coloque aqui. Se houver alguns efeitos colaterais para alguma função em um ambiente "exótico" específico, isso ocorre nesta parte.

^{E se algo no manual for questionável / ambíguo? E se a explicação completa de conceitos particulares dificultar a leitura do manual? E se a versão específica do manual apresentar erros?}

Duas coisas a considerar para os mantenedores são:

1. Especificação técnica / formal.
   Sempre que houver um tópico questionável / ambíguo / difícil de explicar no manual, o leitor pode ser referido a um parágrafo específico da especificação para uma declaração "oficial" estrita e clara sobre isso. Uma descrição rigorosa e completa (e provavelmente muito chata) da sintaxe da linguagem seria melhor.
   As considerações fundamentais para a Especificação são a precisão e a completude técnicas, mesmo que elas ocorram à custa da legibilidade.
2. Suplemento online.
   Basta reservar um URL e colocá-lo no início de cada documento que você liberar, para que os caras que estão se perguntando o que diabos acabaram de ler possam ir lá (em vez de incomodar os mantenedores manuais) e encontrar o erro explicado.

   _{Errata> Fundamentos> Release 2.2> Typo na página 28, segunda começa frase com sorte , leia bloqueio em seu lugar.}

Por exemplo, os mantenedores manuais aparentemente estariam interessados ​​em uma descrição completa e precisa da concorrência e do bloqueio na especificação formal - coloque-a lá. Os leitores de tópicos Fundamentos ou Avançados podem estar interessados ​​em uma visão geral / introdução / guia extraída da especificação e adaptada às suas necessidades, etc.

_{Pode ser útil organizar um estudo comparativo da documentação de referência fornecida para outros idiomas como o seu. Aponte este estudo para aproveitar a experiência adquirida por aqueles que o fizeram antes e aprender a evitar erros que cometeram.}

_{O último, mas não menos importante, considere configurar o desenvolvimento da documentação de maneira semelhante ao desenvolvimento de software. Quero dizer coisas como controle de versão, lançamentos regulares, rastreamento de problemas, garantia de qualidade, etc. Você pode fazer alguns compromissos, se for constatado que o (s) seu (s) escritor (es) técnico (s) não estão realmente confortáveis ​​com coisas assim. Não queremos obter conteúdo de baixa qualidade "em troca" de um processo de desenvolvimento perfeito, não é?}

A primeira coisa que você precisa fazer é avaliar o público. É o seu público-alvo hackers de kernel Linux ou eles são designers de hardware que usam ferramentas de software para fazer um trabalho, mas não estão interessados ​​em software por si só e não têm experiência em CS. É provável que os engenheiros elétricos não sejam totalmente claros sobre as diferenças entre argumentos const e não const, ponteiros para objetos versus referências etc. Se suas primitivas sobrecarregaram nomes, é melhor você explicar esse conceito em um nível apropriado para o seu público, o que pode não ser nada se forem programadores em C ++.

A segunda coisa que você precisa avaliar é a granularidade das primitivas da linguagem. Quanto mais fina a granularidade, mais você precisará fornecer exemplos de uso nas proximidades das especificações de sintaxe de cada primitivo. Ou seja, se você tem uma primitiva de baixo nível que instancia algum contexto e precisa operar com outras três primitivas de baixo nível antes de poder fazer algo útil, é melhor ter um exemplo completo de algumas funções úteis por no manual. Veja a documentação do openssl online para um excelente contra-exemplo de documentação quase inutilizável.

Certifique-se de incluir uma explicação dos efeitos colaterais de suas funções.

De qualquer forma, se você não quiser que os programadores de seus clientes o amaldiçoem todas as noites antes de dormir, inclua vários códigos de exemplo testados que executam algumas primitivas funcionais de alto nível. Certifique-se de que os exemplos não sejam apenas trechos de código, mas completos e compiláveis ​​ou executáveis ​​prontos para o uso.

Tradicionalmente, os escritores de tecnologia distinguem entre manuais de referência e guias do usuário . O manual de referência geralmente inclui as especificações de sintaxe, uma definição inteligível das funções ou primitivas, discussão de pegadinhas, desempenho e efeitos colaterais e um breve exemplo de uso. O guia do usuário inclui exemplos de uso mais estendidos e discussão de problemas de engenharia mais amplos. A "Linguagem de programação C" de Kernigan e Ritchie é um excelente contra-exemplo para esta convenção, mas essa abordagem funciona apenas quando o idioma que você está documentando é relativamente simples.

O autor foi gerente da Divisão de Serviços de Engenharia no centro de desenvolvimento da Ready Systems Inc entre 1987 e 1991, com a responsabilidade de gerenciar uma equipe de cinco redatores de tecnologia.