Flux de travail et meilleures pratiques pour la documentation
Nous avons créé un ensemble de modèles très personnalisés qui changent de temps en temps, mais qui comportent également des parties similaires, thème par thème. Je cherche à rationaliser la manière dont nous créons notre documentation afin de la transmettre aux utilisateurs. Je me suis tourné vers la communauté WPA pour voir ce qu'ils utilisent pour créer des documents. Je pensais créer un type de Wiki à transmettre aux clients sur lequel nous allions construire au fur et à mesure, mais je ne sais pas encore comment le faire.
Quelqu'un peut-il partager ses expériences, ses épreuves, ses tribulations?
Merci d'avance!
Jn
Excellente question. Il n'y a pas de flux de travail de documentation générique et complet dans les cercles WordPress. Cependant, il existe quelques outils et options de Nice à utiliser.
readme.txt
Fichier lisible par machine basé sur Markdown. Son objectif principal est d'être analysé et présenté par le référentiel de plugins officiel, mais ce n'est pas très pratique en dehors de cela.
C'est un endroit formidable et approprié pour la première vue d'ensemble, mais pas pour les instructions avancées.
Aide contextuelle
L'aide contextuelle dans les panneaux d'administration venait tout juste (relativement) de devenir utile. Excellent endroit pour les instructions d'interface utilisateur, les liens vers des ressources locales et distantes et peut-être une courte FAQ.
Le problème majeur étant qu’il s’agit d’une chose nouvelle et sous-utilisée, les utilisateurs n’auront probablement pas à chercher des informations là-bas. La solution de contournement facile consiste à déclencher son ouverture conditionnelle - par exemple la première fois ou jusqu'à ce que l'utilisateur effectue les opérations requises (configuration, etc.).
PHPDoc
La documentation en ligne est essentielle pour les développeurs. Facilite l'apprentissage ou la maintenance du code. Très utile dans les IDE.
Un aspect un peu moins évident est que, avec quelques efforts, la documentation en ligne peut être utilisée comme source pour générer des documents plus conviviaux. Des exemples de références sont les références croisées, mais il existe de nombreuses possibilités moins communes à explorer telles que générer des pages wiki (plug éhonté).
Outils non spécifiques à WP
Outre ce que WP et PHP offrent, il y a évidemment beaucoup d'autres choses que vous pouvez faire, en fonction de vos besoins et de ceux de vos clients.
Les solutions hors WP typiques utilisées sont les wikis (ou uniquement les sites avec des documents), les outils de suivi des problèmes, les services de support de la communauté hébergée, etc.
En outre, il avait été envisagé de mélanger une documentation étendue dans WP lui-même. Dans le cas le plus simple, il peut s’agir simplement d’enrichir le fichier readme.html avec plugin. Mais il existe également des possibilités plus complexes, comme l'utilisation de types de publication personnalisés pour les documents .