Como escrevo páginas de manual? [fechadas]

16

Como escrevo uma página de manual?

Onde posso encontrar uma referência para todos os códigos de formatação?

Existem bons tutoriais sobre como escrever páginas de manual?

Qual é a maneira mais conveniente de escrever uma página de manual? Devo inseri-lo diretamente em um editor de texto? Existem editores WYSIWYG? Ou devo escrever em um formato diferente e depois converter?

Quais regras uma boa página de manual deve seguir?

documentation amarillion
fonte
Esta questão parece ser muito ampla. Ele conseguiu atrair apenas um monte de respostas somente para links e algumas opiniões sem suporte.
200_success 15/10/2014
man man, man groff.
Jenny D

Respostas:

6

Existem ferramentas para escrever páginas de manual que ignoram a formatação de troff. As páginas de manual são uma linguagem pequena e bem delimitada e fácil de segmentar.

Duas ferramentas populares são:

yodl e zoem parecem ser outros formatos legais neste espaço.

Em suma, eu recomendaria o xmltoman porque é um dsl muito específico da página de manual que o guiará de perto.

Tobu
fonte
"dsl" == "idioma específico do domínio"?
Pausado até novo aviso.
sim (. da si 15 caracteres..)
Tobu
11
Outra boa opção é ronn , que lê a linguagem de marcação de texto Markdown mais amplamente usada.
poolieby
5

Eu escrevi um artigo bastante extenso sobre o tópico, que você pode encontrar aqui:

http://2buntu.com/articles/1034/how-to-write-a-manpage/

Nathan Osman
fonte
4
Seria útil se você pudesse ao menos resumir o artigo aqui - os links sozinhos não valem quando a página vinculada inevitavelmente se move ou desaparece.
Caleb
Eu não concordo com Caleb. Esta é a web. A web é baseada em links e o stackexchange não carrega nenhuma exceção especial. Copiar conteúdo é contraproducente. Qualquer coisa ruim que possa acontecer com essa página ou documento também pode acontecer com esta . Não podemos acumular cópias raspadas de todo o conteúdo apenas porque o restante da Web pode desaparecer. (Deixe esse trabalho em sites como a máquina de retorno).
Kaz
Kaz, você pode não concordar, mas o comentário de Caleb é definitivamente a melhor prática do ServerFault.
MadHatter suporta Monica
2

Não conheço nenhum IDEs ou tutoriais, mas você pode começar copiando uma página de manual existente e modificá-la para atender às suas necessidades.

Para uma referência da linguagem groff com macros MAN (que é usada por uma página de manual), consulte a página de manual groff_man ou leia-a on-line aqui

Dan Andreatta
fonte
2

Dê uma olhada no projeto ronn . É uma redução para o gerador de páginas de manual. Ele também pode gerar as páginas do manual em HTML, como este .

Eu gosto da idéia de escrever toda a documentação do meu software em um formato. Markdown IMO é uma boa escolha

Bruno Polaco
fonte