Contribuer à la documentation rapide

L’équipe de documentation Fedora. Version all versions Last review: 2023-08-25
L’objectif est se passer des wikis, où les guides utiles sont mélangés avec des brouillons de documentation et des notes internes. Nous souhaitons rédiger des guides se concentrant sur un sujet à la fois et des tutoriels avec du code source de partout, ajoutables par une simple pull request. Merci d’avance pour votre aide !

Étapes

  1. Choisissez un document à mettre à jour. Vous trouverez les documents à mettre à jour dans le fichier modules/ROOT/nav.adoc. Ils se trouvent dans les lignes commentées (celles qui commencent par //FIXME).

  2. Créez un fork du dépôt https://pagure.io/fedora-docs/quick-docs.

  3. Modifiez le fichier .adoc de votre choix.

  4. Décommentez le fichier dans nav.adoc et supprimez le FIXME du xref.

  5. Compilez localement un aperçu de vos modifications afin de les vérifier. Pour ce faire, assurez-vous d’avoir Podman ou Docker d’installé, et exécutez ./docsbuilder.sh sous Linux, ou bien ./docsbuilder.sh -p ou ./preview.sh sous macOS. Il ne reste plus qu’à suivre les instructions à l’écran.

  6. Lorsque vous êtes satisfait·e de vos modifications, envoyez une pull request.

  7. Si vous effectuez la migration d’une page de wiki, créez une redirection sur l’ancienne page – voir ci-dessous.

Suggestions de contenus à adapter

Peut-être souhaitez-vous simplement améliorer un document existant, auquel cas, ce qui précède est tout ce dont vous avez besoin. Ou peut-être avez-vous déjà une idée en tête. Si vous souhaitez apporter votre aide mais vous ne savez pas par où commencer, voici quelques sources d’inspiration :

  • L’ancienne catégorie How To sur le wiki Fedora. Une grande partie de ces documents mériteraient d’être convertis. (Une grande partie d’entre eux est également (très) obsolète !)

  • Les questions de la section Common Issues dans Ask Fedora.

  • Les questions à propos de Fedora posées fréquemment sur Stack Exchange.

  • Les articles du Fedora Magazine. Le format du magazine est plutôt décontracté et les contenus ne sont généralement pas mis à jour. L’adaptation pour la documentation rapide doit être droite-au-but et mise à jour en suivant l’évolution des commandes ou des bonnes pratiques.

Redirections à partir du wiki

Habituellement, les wikis ne permettent pas de rediriger vers des sites externes, car le risque d’abus est très élevé. Nous avons développé un plugin pour le wiki Fedora qui autorise les redirections vers les pages de ce site, https://docs.fedoraproject.org/. Pour créer un tel lien, utilisez la macro #fedoradocs en mettant quelque chose comme ceci en haut de la page du wiki devant être remplacée :

{{#fedoradocs: https://docs.fedoraproject.org/en-US/council/fpl/}}

Bien entendu, vous devez remplacer cette URL spécifique par celle de votre nouvelle page. L’URL ne peut pas être arbitraire – elle se doit de commencer par https://docs.fedoraproject.org/.

Une fois la redirection en place, les visiteurs de cette page wiki seront instantanément dirigés (enfin, redirigés, avec le code 301 Moved Permanently) vers le site de la documentation.

Notez qu’il n’y a pas de validation de l’existence ou de l’exactitude de la cible. Pensez donc à vérifier que les redirections que vous créez fonctionnent correctement avant de passer à autre chose.

Si vous avez besoin de modifier une telle page pour corriger l’URL, ou pour supprimer complètement la redirection, construisez une URL vers le wiki contenant &action=edit, comme ceci :

https://fedoraproject.org/w/index.php?title=Project_Leader&action=edit

Want to help? Learn how to contribute to Fedora Docs ›