Bonnes pratiques pour la rédaction

Pour garantir que la documentation de Pristy reste claire, cohérente et facile à maintenir, nous vous invitons à suivre les bonnes pratiques suivantes lors de vos contributions.

Structure et Métadonnées (Front Matter)

Chaque page doit commencer par un bloc de métadonnées (le front matter) correctement rempli. C’est essentiel pour le référencement, la navigation et l’affichage des pages.

• title: Le titre officiel de la page. Il est utilisé pour les menus, les liens et le référencement (SEO). Il doit être concis et mis entre guillemets.
• display_title (Optionnel): Utilisez ce paramètre si vous souhaitez que le titre <h1> affiché en haut de la page soit différent (par exemple, plus long ou plus descriptif) que le title. S’il n’est pas défini, le title sera utilisé par défaut.
• description: Une phrase courte qui résume le contenu de la page, essentielle pour le SEO. Mettez-la entre guillemets.
• weight: Un nombre qui définit l’ordre d’affichage des pages dans les menus.

Formatage du Contenu

La manière dont le contenu est écrit et structuré est essentielle pour la lisibilité.

Titres et Sections

• Ne mettez jamais de titre de niveau 1 (#) manuellement. Le thème s’en occupe automatiquement en utilisant display_title ou title.
• Structurez votre page avec des titres de niveau 2 (##) pour les sections principales.
• Utilisez des titres de niveau 3 (###) et inférieurs pour les sous-sections.

Terminologie Spécifique

• Noms de produits Pristy: Gardez la casse et l’orthographe exactes : Pristy, Espaces, Actes, Marchés, Social, Portail.
• Marques tierces: Mettez les noms de marques qui ne sont pas Pristy entre backticks (apostrophes inverses), par exemple : GitLab, Docker, Alfresco.
• Termes anglais: Mettez les termes techniques anglais courants en italique et faites suivre de leur traduction française la plus fréquente entre parenthèses.
  • Exemple : Ouvrez une merge request (demande de fusion).

Listes

• Pour les listes à puces ou numérotées, commencez chaque élément par une minuscule.
• Terminez chaque élément par une virgule s’il n’a pas de ponctuation et que la liste continue.
• Utilisez un point pour le dernier élément de la liste.

Exemple de liste :

1. choisissez le projet pertinent,
2. créez une branche avec vos modifications,
3. ouvrez une merge request (demande de fusion).

Ton et Style

• Adoptez un ton professionnel, clair et direct.
• Utilisez le vouvoiement (“vous”) pour vous adresser au lecteur.
• Privilégiez les phrases courtes et les paragraphes aérés pour faciliter la lecture.

En respectant ces quelques règles, vous nous aiderez à construire une base de connaissances de grande qualité. Merci pour votre contribution !