Guide de style de documentation

Le guide de style est conçu à la fois pour les contributeurs de la documentation et les éditeurs linguistiques. Le guide de style doit être appliqué de manière uniforme pour garantir la qualité, la cohérence et la lisibilité du contenu.

Au préalable

• Assurez-vous de comprendre votre public en premier. Votre contenu est exposé à des audiences ayant des antécédents techniques et des compétences variées. Veillez à ce que votre travail soit accessible aux lecteurs novices et expérimentés.
• Choisissez soigneusement votre sujet. Votre contenu doit être structuré autour de ce sujet.
• Assurez-vous de comprendre le type de votre contenu. Par exemple, votre contenu est-il un tutoriel pas à pas, une vue d'ensemble technique ou un essai pour le grand public ?
• Déterminez la portée et les prérequis de votre contenu.
• Adoptez un guide de style approprié.

Ton et style général d'écriture

• Nous encourageons les rédacteurs à utiliser un anglais simple et à aider les lecteurs à comprendre facilement le contenu. Il peut être utile de rendre votre contenu clair et concis.
• Assurez-vous que vos paragraphes sont structurés autour d'un sujet unifié. Vos phrases doivent être courtes, grammaticalement solides et linguistiquement cohérentes.
• Nous encourageons l'utilisation d'un vocabulaire inclusif comme style d'expression universel.

Langue et grammaire

• L'anglais américain est généralement préféré.
• Pour un nouveau terme, écrivez d'abord le mot suivi de son abréviation. Pour les abréviations courantes telles que RESTful API et HTML, pas besoin de les préciser.
• Le ton de votre écriture doit correspondre au sujet et à l'objectif. Lorsque vous voulez créer une tonalité plus personnelle, utilisez la deuxième personne.
• L'emploi de la voix active est préférable à la voix passive lorsque c'est possible.
• Utilisez le temps présent pour écrire votre brouillon.
• Accordez une attention particulière à votre grammaire, notamment :
  • L'orthographe américaine. Par exemple, utilisez "center" au lieu de "centre".
  • Les articles définis et indéfinis. Vous pouvez exclure ces articles des titres et des en-têtes.
  • La capitalisation correcte. Utilisez la casse de phrase pour les titres et les en-têtes.
  • Les pronoms doivent avoir des indications claires. Par exemple, "It is the best exploratory data analysis tool" ne précise pas qui est "it". Pour éviter toute imprécision et confusion, reformulez la phrase comme suit : "RATH est le meilleur outil d'analyse de données exploratoires".
  • Veillez à ce que votre ponctuation soit correcte conformément aux règles courantes.

Éditez votre contenu

Maintenant que vous avez un brouillon, vous êtes à mi-chemin du processus. Assurez-vous d'avoir effectué les étapes suivantes d'édition linguistique avant de soumettre votre contenu.

• Lisez-le à nouveau. Comme bonne pratique, demandez à un collègue de vous donner des commentaires.
• Pendant la lecture, tenez compte des problèmes suivants :
  • Votre contenu est-il facilement compréhensible pour votre public ?
  • Votre contenu est-il bien structuré ?
  • Contient-il des exemples qui facilitent la compréhension du lecteur ?
  • Les informations techniques sont-elles correctes ?
  • Y a-t-il des informations sensibles que vous ne souhaitez pas divulguer ?
  • Surtout, qu'apprend votre public de votre contenu ?

Soumettez votre contenu

RATH Doc Center utilise Docusaurus comme plateforme de gestion de contenu.

Vous pouvez utiliser Markdown, un langage de balisage populaire auprès de nombreux rédacteurs techniques et programmeurs, pour créer et modifier des documents.

Contactez-nous pour mettre en place un flux de soumission pour vous.