Comment écrire de la documentation technique d'un site web/logiciel pour les nouveaux développeurs?
Je veux faire une documentation technique d'un site web existant pour les développeurs afin que les nouveaux développeurs peuvent continuer à travailler avec elle. Dans les codes existants, peu (ou pas du tout) dans les commentaires de code ou doc-les chaînes de caractères sont disponibles (mauvaise pratique, je sais). Ouais, j'ai vu certains messages liés à ces. Mais ceux qui n'ont pas été détaillés. Voici mes questions:
- Quoi?
- Comment l'organiser? Je veux dire, pouvez-vous suggérer une certaine hiérarchie, de sorte que les nouveaux développeurs peuvent facilement obtenir sur la piste?
- Quelles sont les meilleures pratiques?
- Pouvez-vous montrer quelques échantillons?
- Comment cela peut-il être facile? Certains ppl suggère outil wiki mais je ne sais rien à ce sujet, il sera utile? Pouvez-vous suggérer n'importe quel outil de certaines de départ rapide tutoriel?
Je n'ai jamais fait un. Donc, j'apprécie tout genre de réponse. Merci à l'avance.
(Les liens seront utiles, mais s'il vous plaît donner un moyen rapide et lucide sommaire)
OriginalL'auteur mshsayem | 2009-09-01
Vous devez vous connecter pour publier un commentaire.
Rapide et lucide:
Pense comme n'importe quel papier.
Quel est le objectif de l'application (site web)? [pourquoi?]
Comment atteindre cet objectif?
Quels sont les problèmes qui ont surgi?
Quels sont les problèmes qui pourraient survenir?
Ce qui pourrait être élargi? [pourquoi?]
Quels sont les problèmes qui pourraient expansion de la cause? [pourquoi?]
Ce nommage/conventions de mise en forme devrait continuer à suivre?
Je pense qu'il y a encore beaucoup à définir sur la façon de décrire le texte en gras. Ce que les diagrammes à utiliser pour la conception de schéma de navigation, ajax communication, etc ... UML du langage de modélisation ne permet pas de couvrir ces lacunes.
OriginalL'auteur Nona Urbiz
En plus de Nona de la suggestion, je dirais aussi qu'il est important de briser le code et d'expliquer les conventions et les intentions du code de sorte qu'il existe une uniformité entre les développeurs pour des choses comme les valeurs d'ID, les classes CSS, JavaScript et les noms de fonction. Soyez aussi précis que vous déterminer nécessaire pour prévenir une nouvelle personne à l'équipe de réinventer le travail.
OriginalL'auteur
Si vous êtes à la recherche d'un moyen rapide pour obtenir votre code, essayez .NET Réflecteur. Il vous donne un large aperçu de toutes vos classes, méthodes, propriétés, etc. de sorte que vous pouvez écrire toutes les techniques de la documentation dont vous avez besoin sans passer à travers le fichiers. Il est super facile à parcourir et il va même vous montrer le code lui-même.
OriginalL'auteur Jason
Avez-vous pensé à la représentation de ce qui est là avec une notation UML? C'est ce que UML est pour! Si les nouveaux développeurs sont de bonne qualité, alors ils devraient être en mesure de le comprendre.
OriginalL'auteur Evernoob