MS Word est mal! Y at-il une bonne alternative? [fermé]

StackOverflow https://stackoverflow.com/questions/862298

Question

En tant que développeur, je n'aime vraiment pas écrire de la documentation, mais quand je dois je voudrais rendre le processus aussi indolore que possible.

Le problème avec Word est que est constamment à ma façon . Je me inquiète plus sur la mise en page que sur le contenu réel ... c'est pourquoi je voudrais vous débarrasser de Word.

Idéalement, je voudrais écrire mon contenu, puis « compiler » dans un document.

Je l'ai entendu parler de LATEX mais je n'ai aucune expérience avec ce que ce soit. Serait-ce la bonne technologie pour le travail? Quel éditeur (Windows) dois-je utiliser? Est-ce une bonne idée de commencer par LyX ?

EDIT: Je ne demande pas sur le code documentation (j'utilise Sandcastle pour cela)

.

Mise à jour 2014:

Nous avons passé à GFM (GitHub aromatisée Markdown) .

  • Il est vraiment facile de travailler avec.
  • Ecrire le code et la documentation dans le même IDE!
  • Tout peut être versionné!
  • Obtenir une grande sortie soit comme txt cru, html ou pdf
Était-ce utile?

La solution

J'ai trouvé que les wikis peuvent être bons pour cela. Trouver un wiki vous aimez qui vous permet de faire un bits de la mise en forme, mais rien de vraiment lourd. Idéalement, il devrait vous laisser le code de format facilement trop -. Pour être honnête, le démarquage disponible sur le SO est probablement un bon début

De cette façon:

  • Vous avez intégré le suivi des modifications (en supposant un wiki décent)
  • Vous pouvez modifier partout
  • Tout le monde voit toujours la même documentation (diffusion instantanée)
  • Vous pouvez vous concentrer sur le contenu au lieu de la mise en forme

Autres conseils

Ma solution à c'était d'investir un peu de temps dans la création d'un mot décent modèle pour moi-même.

La chose importante à faire est de vous assurer que vous avez un style défini pour tout ce que vous pouvez mettre dans le document.

Une fois que vous avez tous les styles définis et tout le contenu du document étiqueté avec le bon style au lieu de mise en forme d'une manière ad hoc, vous serez surpris de voir comment il est facile de produire une bonne recherche documents Word rapidement à chaque fois.

Le problème plus large est que tout le monde passe des heures dans Word et pourtant il est très rare pour les entreprises à investir dans la formation Word. À un certain moment, vous devez mordre la balle et prendre le temps de vous apprendre à l'utiliser correctement, comme vous le feriez avec tout autre outil.

Tout ce que vous pouvez faire avec LyX vous pouvez faire avec LaTeX. LATEX convient à toutes sortes de choses; il a été utilisé pour tout, de manuels pour donner des conférences diapositives romans.

Je pense que probablement LATEX dignes d'intérêt comme une option; si vous avez toujours voulu « code » pour votre traitement de texte, LaTeX est pour vous. Au niveau le plus simple, vous pouvez définir de nouvelles commandes pour faire des choses pour vous, mais il y a beaucoup de puissance là-bas. Et les regards de sortie vraiment propre.

À mon avis, LyX est fantastique dans certaines circonstances, à portée de main dans d'autres, et parfois juste met sur votre chemin. Je pense qu'il devrait être considéré comme un rappel de la productivité pour LaTeX. En d'autres termes, apprendre à utiliser LaTeX avant d'essayer LyX . Les deux sont bien sûr gratuit et disponible pour Windows, bien que la courbe d'apprentissage est assez raide par rapport à MS Word. Pour les longs documents, ou beaucoup de documents similaires, LATEX / LyX est probablement un bon investissement.

Vous pouvez écrire votre documentation en utilisant votre propre format XML, puis le transformer en un format avec XSL (par exemple PDF via FOP + XSL-FO). Voir aussi la format XML de DocBook.

est un LATEX très outil puissant et pourrait bien être surpuissant ici car il est conçu pour la littérature scientifique / mathématique. Il a une (relativement) courbe d'apprentissage abrupte et peut être difficile à amadouer faire exactement ce que vous voulez si vous êtes nouveau pour elle. J'AIME LATEX, mais il est pas vraiment un processeur général mot fin.

Avez-vous envisagé OpenOffice à la place?

LATEX est vraiment une langue très puissant si vous avez besoin d'écrire des documents.

Peut-être que vous pouvez essayer texmaker , un multi-plateforme LATEX éditeur:

  

Texmaker est propre, très   configurable éditeur de LaTeX avec une bonne   soutien clé chaud et vaste latex   Documentation. intègre texmaker   de nombreux outils nécessaires pour développer   documents LATEX, en un seul   application. Il a une belle   des fonctionnalités telles que la coloration syntaxique,   insertion de 370 symboles mathématiques   avec un seul clic, et « la structure   vue » du document pour faciliter   la navigation.

Qu'en est-il en utilisant HTML? De cette façon, vous pouvez ensuite publier la documentation s'il y aura besoin pour beaucoup de gens à y accéder de nombreux endroits.

En dépit de tous les efforts et les attentes raisonnables, je ne pense pas de traitement de texte a été « résolu » encore.

Ma réponse à ce que je trouve personnellement une expérience très frustrante avec MS Word est d'éviter complètement et utiliser un outil documentant automatique comme GhostDoc générer XML ce que je l'ai déjà écrit dans le code (SEC!) et de traiter le XML à partir un site intranet XSLT ou similaire plus tard.

Parlez-vous de documenter votre code réel? Si oui, je vous recommande Doxygen code non managé et Sandcastle pour le code managé. Les deux compilera votre aide ou construire un site Web pour vous.

Les deux applications lire les étiquettes spéciales fonctions ci-dessus / classes / variables et compiler que dans l'aide.

Eh bien, je ne l'ai jamais trouvé quelque chose de mal avec MS-Word en premier lieu. (I.e. si vous prenez le temps de savoir comment l'utiliser efficacement). OpenOffice est en effet une étonnante et sans alternative crédible - mais si vous détestez MS Word pour les problèmes liés à la mise en page, la même problème se produit va avec OpenOffice aussi.

jamais essayé le Latex système moi-même , mais qui ont entendu son bon pour le travail scientifique. Je pense en utilisant un éditeur HTML WYSIWYG serait le mieux pour vous, si vous voulez vous concentrer uniquement sur le contenu.

Je considérais comme un wiki, mais j'ai décidé d'aller avec une notation de Markdown modifiée, pour la simple raison, que le contenu d'un wiki est pas facilement exporté et distribué en dehors du wiki lui-même, alors que le Markdown peut être rendu en HTML.

Réponse à la question de chris à propos de mon flux de travail: J'écrire la documentation avec une application comme le Bloc-notes ( TextWrangler , seulement en raison de sa caractéristique mot-emballage) dans son format Markdown brut. Ensuite, j'ai un petit site de documentation localhost avec

Je ne l'ai pas eu le temps de l'essayer, mais je l'ai toujours pensé AsciiDoc serait bon pour ce genre de chose.

Si vous voulez quelque chose de plus simple que LaTeX, vous pouvez jeter un oeil à ReStructured texte

Lisez ce livre: http://en.wikipedia.org/wiki/The_Pragmatic_Programmer . Il y a une idée fixe à l'intérieur, de sorte que la documentation doit être construite automatiquement. Pensez à utiliser votre IDE pour cela, ou chercher des outils supplémentaires. La plupart des langues modernes prennent en charge la génération de documentation que vous écrivez le code. Cela peut simplement maintenir votre doc en contact avec les dernières modifications du code.

Je préfère utiliser un éditeur RTF qui est beaucoup moins clunkier que les mots. De cette façon, la mise en forme et tous les en-têtes / pieds de page non-sens ne prendra pas la moitié de votre temps. Wordpad a travaillé pour moi à plusieurs reprises. Je suis coincé avec Word pour l'instant si: (

il y a beaucoup de façons possibles:

  • documentation intégrée, par exemple javadoc: bon pour décrire les API, pas si bon pour la « grande image »
  • html simple: peut être vérifié dans le contrôle de version, un plus indéniable
  • un wiki, par exemple confluence - grande pour la collaboration, mais a le contrôle de version différente de votre source
  • ou somesuch LATEX: mieux adapté pour les livres ou documents que la documentation typique; soutien graphique est lourd
  • un clone de bureau, par exemple OpenOffice: la plupart du temps la même que Word + Visio, mais open source, avec un format plus agréable document

Je documente habituellement la structure logicielle (les « métaphores » d'un projet, interrelation des composants, des systèmes externes) à l'avant, en utilisant Visio, UML « forme libre ». Ceux-ci sont ensuite intégrés dans la confluence, qui peut être converti en PDF si quelqu'un veut une impression.

LyX

LyX est un

Vim est la solution pour tout ce qui veut dire écrire le texte brut de la manière la plus efficace possible. Si vous avez besoin de mise en forme, puis utilisez XML, latex ou quelque chose de similaire (en VIM).

Vim a changé ma vie!

Réponse simple:. LaTeX ressemble exactement ce que vous cherchez

Je l'utilise pour écrire de la documentation moi-même. Je ne pourrai jamais revenir à Word si je l'option.

PHC , nous avons commencé avec le latex, puis déplacé à DocBook et se sont installés (de façon permanente je l'espère) sur Restructuré texte / Sphinx.

latex a été choisi parce que nous sommes des universitaires, et le latex est l'outil de choix. Je crois qu'il n'a pas généré assez bon HTML.

DocBook a été choisi pour le pouvoir, mais il était très difficile à manier. Il nous rebutés par écrit toute la documentation: le code a dû être formaté manuellement, nous oubliaient la syntaxe, et il était difficile de lire. La courbe d'apprentissage a été aussi forte.

Enfin, nous avons déménagé à reST , en utilisant sphynx, et ce fut une bonne décision. La documentation est maintenant très facile à écrire, et à la fois PDF versions HTML paraissent beaux (bien que le PDF pourrait faire avec une certaine personnalisation). Il est très facile à personnaliser aussi.

Le meilleur atout de reST cependant, est que son lisible par l'homme sous forme source. C'est un avantage merveilleux. Je suis passé à l'aide Reposez-vous pour toutes mes affaires maintenant, en particulier tout sur le Web (à l'exception bien sûr des documents universitaires, où l'on serait insensé d'utiliser autre chose que le latex).

Vous pouvez regarder dans doxygen http://www.doxygen.nl/ , voir leurs beaux exemples. Dans ce cas, la documentation est présentée par les balises dans les commentaires de la source.

Une autre option serait d'utiliser un système en ligne comme http://trac.edgewall.org/ qui est un système wiki / doc / IssueTracking qui vit au-dessus de la subversion.

Licencié sous: CC-BY-SA avec attribution
Non affilié à StackOverflow
scroll top