Quels outils sont utilisés pour écrire de la documentation?

Question

Quels outils sont utilisés pour écrire de la documentation?

Spécifiquement pour

• Documents utilisateur
• L'administration du système
• Développement

Je recherche des logiciels tels que MS Word, wiki, TeX (LaTeX, LyX) et des outils automatisés.

Answer 1

J'ai récemment découvert le Dr Expliquer ce qui est idéal pour la création de l'interface utilisateur de la documentation. Il va en et brise tous les éléments de l'interface utilisateur (boutons, éléments de menu, les boîtes d'édition, etc.) à partir de votre application en cours d'exécution, puis des extraits des méta-informations, il peut à l'ouverture de votre dossier (voir capture d'écran). Ensuite, tout ce que vous avez à faire est de supprimer ou modifier les éléments qu'il trouve et de modifier les descriptions. Produit professionnel de l'interface utilisateur de la documentation très rapidement. Il a aussi tout l'autre extrémité de l'utilisateur de la documentation d'aide de fonctionnalités que vous attendez.

Cette capture d'écran vous montre l'une des images qu'il crée pour vous. Il a été créé en la pointant vers une fenêtre de préférences. Il ajoute ensuite le petit numérotés boîtes bleues sur le visible commandes de l'utilisateur. Il permet également d'extraire le texte et le type de contrôle de l'information (bouton, case à cocher, etc.) ainsi que d'autres méta-informations. Ces images peuvent être cliquable trop, pour permettre de forer vers le bas à partir de la capture d'écran.

Cette fonction m'a vraiment bluffé. Il pourrait ne pas être le meilleur dans l'ensemble, mais cette fonctionnalité a été assez incroyable.

Answer 2

- Je écrire en Markdown, la même mise en forme de la syntaxe que nous utilisons sur un Débordement de Pile. Parce que les documents sont en texte brut, ils peuvent vivre aux côtés de code dans le contrôle de version. C'est utile.

J'ai rendu les documents au format HTML et PDF avec le couteau de l'armée suisse Pandoc. Avec une courte feuille de style, ces sont de meilleure qualité que les documents de traitement de texte.

---

Si nous parlons de la documentation technique, dans mon esprit il y a deux sortes de documents, dont vous devriez avoir les deux. Pour les bibliothèques et les Api que vous avez généré automatiquement la documentation décrivant les appels de fonction et les types, ce qui est utile pour refernece, mais vous avez aussi besoin prosy guide de l'utilisateur/tutoriel style de la documentation qui peut être lu de haut en bas. :

• Pandoc faible niveau de référence de l'API pour les pirates
• Pandoc prosy guide de l'utilisateur pour les utilisateurs (et les pirates)

Addendum: Vous pouvez utiliser Sphinx pour les deux types de documentation. La sortie est magnifique

• http://scikit-learn.org/stable/user_guide.html
• http://scikit-learn.org/stable/modules/classes.html

Answer 3

Nous avons toujours préféré LaTeX car nos documents ont une tonne de calculs lourds ... Mais, plus important encore, c'est du texte brut qui signifie qu'il est vraiment facile à gérer avec notre VCS (CVS, SVN, Git, etc.) et qu'il peut facilement vivez directement avec le code - il n’ya donc aucune excuse pour ne pas mettre à jour la documentation au fur et à mesure que vous développez.

En signe d'adieu à Kristopher, nous sommes une organisation assez scientifique (mais pas un .edu) ...

Answer 4

J'utilise Visio pour générer UML docs et des échéanciers. Pour moi, ce sont tous fait lors de la conception, quand je suis à essayer de comprendre comment je veux que les choses organisées, ou comment les choses devraient fonctionner. Ensuite, (je l'espère), ils sont mis à jour après la mise en œuvre est effectué afin qu'ils correspondent à ce qui a été fait (mise en œuvre ne correspond jamais avec la conception exactement!).

Pour une documentation du code j'utilise quelques outils, en fonction de la langue. L'ensemble de ces variations sur la javadoc de commentaires, que j'aime.

• Java - javadoc
• C/C++ - doxygen
• Actionscript 2 - as2api

Visual Studio est doté d'un outil de documentation pour C# (et probablement d'autres .Net languages) qui utilise XML comme des commentaires. Je crois que d'autres ont mentionné que.

Pour le reste de notre documentation (protocole de Réseau, etc), nous utilisons un Wiki d'entreprise. Nous sommes à l'aide de la Confluence, bien qu'il existe beaucoup de Wiki choix. Nous trouvons l'utilisation des wikis pour être très utile, car il est facile pour quiconque de faire la mise à jour de la documentation lorsque le besoin, et il est également facilement accessible (pas de transfert de fichiers Word).

Answer 5

Pour la rédaction de la documentation pour les utilisateurs finaux, il y a beaucoup de choses à considérer avant de vous commencer à regarder d'un outil particulier. Elles comprennent:

1. Quelles sont vos exigences de l'outil? Cela pourrait inclure de contenu disponible dans un navigateur web, comme HTML" ou "contenu affiché hors CHM", ou les deux.
2. Avez-vous besoin de l'outil pour être assez simple pour que n'importe qui sur votre équipe peut l'utiliser, ou vous avez une technique dédiée écrivain qui va passer sa journée entière dans l'application? Le premier nécessite une simple application qui fait beaucoup de travail pour vous. La seconde nécessite une puissante application souple avec beaucoup de fonctionnalités.
3. Quelle serait la meilleure présentation de votre contenu? HTML, un wiki, un forum, ou autre chose?

Les réponses à ces questions vous permettra de comparer vos options de l'outil. J'ai écrit un post de blog qui va plus dans le détail ici.