Criando um site e uma documentação eficientes da biblioteca C ++

Criar uma biblioteca C ++ também significa documentá-la para que outros possam usá-la e essa documentação possa variar drasticamente em qualidade.

Como um site para uma biblioteca C ++ deve ser estruturado para que seja mais eficaz?

Eu descreveria o "mais eficaz" como sendo dividido entre três grupos específicos de partes interessadas da biblioteca, que devem ser capazes de encontrar e aprender o que precisam para participar e usar a biblioteca:

1. Os novos usuários precisam de uma introdução, download, configuração e documentação excelentes e fáceis que fluam claramente de uma etapa para a seguinte.

2. Os usuários experientes precisam de uma referência sólida com acesso rápido aos detalhes de que precisam e informações claras sobre novas atualizações.

3. Os novos colaboradores precisam de um guia de como abordar as etapas que eles devem executar para obter suas contribuições na biblioteca.

Eu gostaria de descobrir como fazer com que cada um fique muito feliz com o que vê e usa. Esta questão é um meio de cruzamento entre programação profissional e experiência do usuário.

Para exemplos específicos, o Boost é uma das melhores coleções de bibliotecas, mas a instalação inicial, a documentação de referência e a maneira de contribuir pode ser um pouco confuso.

Por outro lado, achei o cppreference.com e a documentação do SGI STL muito claros e úteis com explicações, links e exemplos.

Embora os exemplos sejam meramente opiniões e outros possam diferir, isso ajuda a contextualizar a pergunta que estou fazendo.

Na minha empresa anterior, começamos a gerar documentação e ter um trabalho de IC executado todas as noites e publicá-lo como um conjunto de páginas da web às quais o wiki da nossa equipe se referiria.

Como foi sugerido nos comentários da sua pergunta, usamos doxygen. Uma coisa que eu realmente gostei que foi introduzida na versão 1.8 foi a capacidade de ter um diretório (ou árvore inteira) de documentos de remarcação, enquanto antes esse doxygen era gerado exclusivamente a partir de arquivos de origem.

A estrutura que tínhamos era uma tela de boas-vindas (remarcação), com links para vários lugares. Uma delas era uma arquitetura de produto que mostrava uma visão de 30.000 pés do produto e destacava os principais serviços. Em seguida, a partir dessa página, houve curtidas em outras páginas de descontos que expandiram cada um dos serviços e apresentaram um design de nível muito alto para cada um (visão de 10 mil pés?).

Também na página principal, tínhamos links para coleções de guias do usuário que escrevemos para explicar como usar algum código de utilitário / estrutura comum.

E lentamente começamos a migrar os documentos de design existentes (escritos no MS Word e armazenados no ponto de compartilhamento) para o formato doxygen, que na verdade se mostrou mais fácil do que se poderia esperar. Se não fosse os diagramas, que precisavam ser exportados individualmente e salvos como JPEGs, um documento de design de 20 a 30 páginas poderia ser convertido para o formato de marcação doxygen em cerca de 15 a 30 minutos, e era tão simples que uma cooperativa poderia fazê-lo ^{( *)} .

A beleza que eu adorava em usar doxygen para esse tipo de documentação, além de poder gerar HTML ou PDF a partir da mesma fonte, era que poderíamos vincular toda a nossa documentação diretamente às páginas de referência de classe / função geradas pela análise de arquivos de cabeçalho. Portanto, era uma estrutura muito agradável que iria de "bem-vindo" -> "arquitetura" -> "design" -> até a documentação em nível de classe.

E como tudo estava em ordem decrescente, era muito simples gerar conteúdo (muito mais fácil do que tentar explicar a uma equipe de engenheiros como usar corretamente o MS Word Styles) e a documentação foi verificada ali mesmo com o código-fonte, de forma a novas versões foram introduzidas e o design / arquitetura modificados, a documentação sempre fica sincronizada com ela.

---

^(*) - j / k, tivemos ótimas cooperativas (na maior parte) e elas fizeram muitas contribuições impressionantes para o produto, mas eu fiz uma delas fazer parte da conversão de documentos.