Méthodes simples pour préparer la documentation d'un projet : 12 étapes

Table des matières:

Méthodes simples pour préparer la documentation d'un projet : 12 étapes
Méthodes simples pour préparer la documentation d'un projet : 12 étapes

Vidéo: Méthodes simples pour préparer la documentation d'un projet : 12 étapes

Vidéo: Méthodes simples pour préparer la documentation d'un projet : 12 étapes
Vidéo: 📁Planification & Gestion de Projet pour les Débutants👨‍🏫 2024, Mars
Anonim

Ce wikiHow vous apprend à rédiger de la documentation pour un projet open source. Cette documentation est généralement appelée fichier README. Le README est un document texte ou HTML qui contient des informations importantes pour les utilisateurs et les développeurs sur votre projet.

Pas

Préparer la documentation pour un projet Étape 1
Préparer la documentation pour un projet Étape 1

Étape 1. Écrivez le titre de votre projet

Lorsque vous écrivez un fichier README pour votre projet, la première chose que vous devez inclure est le titre du projet. En plus du titre, vous devez également inclure le dernier numéro de version et la date de sa dernière mise à jour.

Préparer la documentation pour un projet Étape 2
Préparer la documentation pour un projet Étape 2

Étape 2. Rédigez une description de votre projet

La prochaine chose que vous devez inclure dans votre fichier README est une brève description de votre projet. Expliquez ce que fait le projet, pourquoi il existe et quels problèmes il résout. Vous pouvez également inclure toutes les fonctionnalités spéciales, captures d'écran, style de code, technologie ou framework utilisé, ou tout autre élément qui serait utile aux utilisateurs et aux développeurs.

Préparer la documentation pour un projet Étape 3
Préparer la documentation pour un projet Étape 3

Étape 3. Expliquez les exigences de votre projet

Si votre projet nécessite des exigences particulières pour fonctionner correctement, assurez-vous de répertorier ces exigences et instructions, ou un lien vers des instructions sur la façon de les installer.

Préparer la documentation pour un projet Étape 4
Préparer la documentation pour un projet Étape 4

Étape 4. Incluez un échantillon du code

Donnez un exemple clair et concis de l'utilisation de votre projet. Le code doit être facile à comprendre pour les développeurs et l'API doit être clairement visible.

Préparer la documentation pour un projet Étape 5
Préparer la documentation pour un projet Étape 5

Étape 5. Fournissez les instructions d'installation

Expliquez aux utilisateurs comment faire fonctionner votre logiciel étape par étape. Vos instructions doivent être aussi claires que possible. Supposons que vos utilisateurs n'ont aucune connaissance du développement de logiciels ou de l'administration système.

Préparer la documentation pour un projet Étape 6
Préparer la documentation pour un projet Étape 6

Étape 6. Expliquez comment utiliser le logiciel

Dites aux gens comment tirer le meilleur parti de votre logiciel. Fournissez des instructions étape par étape sur la façon d'utiliser votre logiciel ainsi que différentes options de configuration et comment les définir.

Préparer la documentation pour un projet Étape 7
Préparer la documentation pour un projet Étape 7

Étape 7. Indiquez aux utilisateurs comment obtenir une assistance technique

Fournit des liens vers des listes de diffusion, des canaux IRC ou des forums communautaires auxquels les utilisateurs peuvent se tourner pour obtenir une assistance technique. Faites également savoir aux utilisateurs plus expérimentés où soumettre des bogues et des idées pour améliorer le projet.

Si vous trouvez que vous recevez beaucoup des mêmes questions de différents utilisateurs, vous pouvez inclure une FAQ (questions fréquemment posées) dans le cadre de la documentation de votre projet

Préparer la documentation pour un projet Étape 8
Préparer la documentation pour un projet Étape 8

Étape 8. Expliquez comment contribuer

Si vous travaillez sur un projet open source, faites savoir à vos utilisateurs comment ils peuvent contribuer à votre projet. Expliquez toutes les normes que vous avez et fournissez quelques lignes directrices aux contributeurs potentiels.

Préparer la documentation pour un projet Étape 9
Préparer la documentation pour un projet Étape 9

Étape 9. Énumérez les crédits

Donnez toujours du crédit là où le crédit est dû. Assurez-vous de répertorier les noms de tous les contributeurs, ainsi que les liens vers les bibliothèques ou programmes tiers que vous avez pu utiliser. Incluez des liens vers toute inspiration que vous avez pu avoir lors de la construction de votre projet.

Préparer la documentation pour un projet Étape 10
Préparer la documentation pour un projet Étape 10

Étape 10. Fournissez vos coordonnées

Les gens peuvent vouloir vous contacter pour un certain nombre de raisons. Assurez-vous de fournir une adresse e-mail valide que les gens peuvent utiliser pour vous contacter.

Certains pays peuvent exiger des informations supplémentaires, telles qu'une adresse postale ou le nom de la société par la loi

Préparer la documentation pour un projet Étape 11
Préparer la documentation pour un projet Étape 11

Étape 11. Fournissez les informations de licence

Il est important que les utilisateurs sachent comment votre projet est sous licence. Il existe de nombreuses licences standard sur le Web que vous pouvez utiliser. Expliquez quelle licence votre projet utilise, ainsi que les licences de toutes les bibliothèques ou programmes tiers que vous pourriez utiliser.

Vous n'avez pas besoin d'expliquer l'intégralité de la licence dans vos documentations. Informez simplement les utilisateurs de la licence utilisée par votre projet et fournissez un lien vers les informations complètes sur la licence

Préparer la documentation pour un projet Étape 12
Préparer la documentation pour un projet Étape 12

Étape 12. Répertoriez toutes les versions du projet

Assurez-vous de créer une liste de toutes les versions précédentes de votre projet et rédigez une brève description des modifications que vous avez apportées à chaque version.

Des astuces

  • Il est recommandé de commencer à écrire votre fichier README avant de commencer à développer votre projet. Cela vous aidera à réfléchir à votre projet et à ce que vous devez accomplir. Cela vous aidera à développer des directives que vous pourrez communiquer à d'autres contributeurs, et vous serez plus motivé pour écrire votre fichier README au début de votre projet.
  • Assurez-vous de mettre à jour fréquemment votre fichier README et toute autre documentation pendant que vous travaillez sur votre projet.
  • Si votre fichier README est plus long qu'une page ou plus, vous pouvez écrire les sections les plus longues, telles que les instructions d'installation, le guide de l'utilisateur et la FAQ dans un document séparé. Assurez-vous de créer une table des matières pour toute la documentation de votre projet et de fournir un lien vers la documentation appropriée dans le fichier README.

Conseillé: