Est-ce déjà l'heure ? … Je suppose que c'est la même chose pour les personnes qui écrivent des documentations sur leurs extensions. La plupart d'entre nous, en temps qu'utilisateurs, regardent simplement la démo, la description courte, puis nous téléchargeons et installons...
Mais laissez-moi vous donner quelques raisons pour lesquelles nous devons consulter la documentation.
Note : Cet article est une traduction de l'article How to Choose an Extension? Part 3: Documentation écrit par Mike Veeckmans.
Lors du dernier article, nous avons parlé du support, cette fois, nous allons regarder la documentation, qui peut faire partie du support proposé par le développeur. Si vous trouvez une extension proposée par un bon développeur, la documentation sera disponible ! Cela ne signifie pas que les autres extensions ne comportant pas de documentation sont de mauvaise qualité, mais une documentation peut vraiment vous aider.
Comment ? Installation, configuration, dépannage, champs suppémentaires, comportements, etc... sont décrits dans une bonne documentation.
RTFM...
Parfois nous “oublions” de lire les 100 longues pages du dictionnaire que quelqu'un a écrit... peut être nous ne voulons pas les lire, mais nous devrions...
Les développeurs qui écrivent des documentations le font principalement pour vous montrer précisément comment utiliser l'extension, quelles sont les possibilités, comme faire les réglages. Cependant, parfois les documentations ne suivent pas les différentes versions de l'extension... p.ex : l'extension est en version 3 alors que la documentation est toujours en version 2. Ce qui est incompréhensible de mon point de vue, est que parfois un développeur doit sortir une nouvelle version en raison par exemple d'un bug, et il n'a pas le temps de réécrire la documentation. Alors que les versions sont très similaires...
Une bonne documentation doit comprendre au moins quatre parties. Installation, configuration, personnalisation et dépannage.
Installation, ce qui est expliqué dans cette partie doit être clair. Et pour les personnes qui pensent qu'il suffit d'installer le pack en passant par le gestionnaire, c'est faux ! Parfois, vous devez ajouter, activer ou désactiver certains plugins, changer une petite configuration sur votre serveur ou dans vos paramètres php... Pour les extensions basiques, vous ne devez pas vous inquiéter bien sûr, mais lorsque vous ajoutez des extensions conséquentes, vous devez faire attention. Je sais de quoi je parle, j'ai rencontré ce problème une fois, et depuis, je n'utilise pas d'extension sans une bonne documentation.
A propos de la configuration ? Cela dépend des fonctionnalités que propose l'extension. Un simple afficheur d'actualité aura une documentation beaucoup moins importante qu'une extension de getsion d'abonnement avec de nombreuses fonctionnalités comme une newsletter, des moyens de paiement, le renouvellement automatique, des groupes d'utilisateurs, etc... Un bon manuel couvrira chaque étape de la configuration, réellement chaque étape. Peut-être que cela va alourdir cette documentation de plus de 20 pages mais mieux vaut lire un peu plus que de s'arracher les cheveux. Même si vous n'allez pas utiliser toutes les fonctionnalités, lisez la documentation, vous pourriez découvrir une fonctionnalité dont vous ignoriez l'existence et que vous pourriez utiliser par la suite.
La partie concernant la personnalisation dépend vraiment de l'extension en question, certaines extensions ne peuvent pas être personnalisées (à part en utilisant les surcharges). Mais si vous en avez choisi une sur laquelle les personnalisations sont possibles, cette partie peut vous être d'une grande utilité. Lorsque j'ai developpé un site comprenant une fonctionalité d'abonnement, le manuel m'a apporté tout ce dont j'avais besoin de savoir à propos de la personnalisation de l'extension et je n'ai pas eu besoin de “déranger” le développeur.
Et la dernière, mais pas la moindre, . Une bonne documentation couvre un grand nombre de problèmes que les utilisateurs peuvent rencontrer. C'est impossible de tous les couvrir car nous n'aurions plus besoin de support, n'est-ce pas... ? Les problèmes qui sont les plus fréquemment rencontrés, et qui ont souvent la même solution, doivent être listés dans cette documentation. Si nous, en temps qu'utilisateur, faisons une erreur, non avons toujours besoin de créer un ticket car ce n'est pas un problème standard...
Donc, les bonnes documentations peuvent beaucoup aider, si le développeur l'a proposé, c'est sa décision. Mais nous, en temps qu'utilisateur, devons la lire, certainement parce que le développeur a passé un temps conséquent à l'écrire...
Vous savez que l'abbréviation RTFM veut dire quelque chose;)