Como entregar documentação para ferramentas de TI?

Question

Gostaria de fornecer uma ferramenta de TI para uso no Windows. A coisa é um filtro ISAPI e desejo descrever a instalação, as operações e a configuração.

Atualmente isso é feito em um arquivo de texto, que é bastante completo, mas acho que não é muito utilizável. Eu acho que tenho um bom controle sobre o que deve estar na documentação. Gostaria de inserir na parte Como . Qual é a melhor maneira de entregar documentação para administradores de servidores web do Windows?

.CHM? .PDF .DOCX .HTM?

EDIT : Eu tinha um arquivo de texto, mas estava ficando muito longo e tinha facilidade limitada para vincular, fazer referência cruzada, indexação e organização. Como vemos, uma seção principal é sublinhada com sinais de igual, uma subseção é sublinhada com traços ... etc etc. Então eu tentei formatá-la dessa maneira, mas no final o arquivo .txt simplesmente não escalou.

Atualizar : selecionei o SHFB. Aqui está a ajuda HTML de saída . O que você acha? utilizável?

    

Answer 1

Aqui está minha opinião:

• O texto ASCII é ótimo - posso ler em qualquer lugar
• HTML é o segundo melhor - eu posso ler isso principalmente em qualquer lugar, também
• O PDF é aceitável, mas um pouco chato, pois talvez eu precise consultá-lo em um servidor com nenhum leitor de PDF instalado
• CHM é uma dor por causa do controle de ajuda HTML estúpido (graças a erros de controle de Ajuda HTML / vunlerabilities!), e não é um formato muito amigável para cortar / colar de
• O DOCX é simplesmente irritante - não tenho o "Office" instalado em meus servidores e, se precisar consultar a documentação, não carregarei

Answer 2

Eu tenho que ir com arquivos de texto ASCII formatados corretamente. Eles podem ser lidos do laptop, servidor, windows, unix, linux, etc.

Eu não deveria ter que confiar em um navegador da web, leitor de adobe, escritório ou qualquer outro programa para ler como instalar algo no meu servidor. Deve ser simples e indolor.

A verdade é ... em um piscar de olhos ... eu poderia até ler o arquivo de texto do meu celular se eu precisasse.

Tenho certeza de que qualquer um que tenha ficado preso em uma instalação às três da madrugada em circunstâncias menos que desejáveis (ou seja, paginadas no bar, sem laptop, etc) concordaria. ; -)

Apenas meus 2 centavos ...

    

Answer 3

Você deve conferir asciidoc . Eu fiz algumas coisas curtas com ele, e a saída é bem nítida (e personalizável, é claro). O texto simples é muito legível por design, e você pode tê-lo docbook, HTML e PDF de saída facilmente. Usando qualquer outro número de conversores, você pode transformá-lo em outros formatos, como o CHM.

Pacote muito versátil, embora seja um pacote centrado em UNIX, não sei como é o suporte do Windows.

    

Answer 4

reStructuredText combina comigo. É fácil aprender e usar.

    

Answer 5

Eu sei que você já aceitou uma resposta, mas eu pensei em recomendar a esfinge . Você escreve o documento em reStructuredText, mas pode facilmente gerar html que é pesquisável (minúsculo javascript). /

    

Answer 6

Aqui está outra votação para texto simples. Se a documentação exigir ou se beneficiar de ilustrações de algum tipo, o HTML pode ser a melhor escolha, pois é mais provável que um navegador esteja disponível do que outros aplicativos de leitura.

Por favor, nunca use o DOCX ou qualquer outro formato proprietário a menos que exista uma razão avassaladora para fazê-lo (e fora de mão não consigo pensar em um único). Mesmo se você quiser criá-lo como um arquivo do Word, salve-o como DOC, e não como DOCX, pois há uma variedade maior de softwares que podem ler o formato antigo.