| Les deux révisions précédentesRévision précédenteProchaine révision | Révision précédente |
| issue65:mon_opinion [2012/10/18 18:39] – andre_domenech | issue65:mon_opinion [2012/10/25 14:05] (Version actuelle) – frangi |
|---|
| La documentation | La documentation |
| |
| Le jour, à mon travail, je suis gestionnaire de projet et l'une des chose que j'essaie sans cesse d'obtenir est une bonne documentation. J'espère en avoir produit un peu moi-même. Mais il n'y a pas de sujet où je rencontre davantage de résistance que la création d'une bonne documentation. Personne n'a jamais le temps d'en créer, mais d'une façon ou d'une autre, ils arrivent à trouver des ressources pour payer le prix quand ils ne l'ont pas. Si obtenir de la bonne documentation est difficile dans le monde des entreprises, quid du monde des Logiciels libres ? C'est tout aussi difficile. Je ne peux pas compter le nombre de fois où j'ai essayé d'accéder au système d'aide pour l'une de mes applications KDE, pour n'arriver qu'à un message m'informant qu'il n'y a pas d'aide disponible. Parfois, vous avez vraiment l'impression que l'on vous dit : « Nous l'avons écrit, à vous maintenant d'essayer de comprendre ce qu'il faut en faire. » Une partie de la raison de cela est que, à mon avis, nous n'y réfléchissons pas comme il faudrait. | Le jour, au travail, je suis gestionnaire de projet et l'une des choses que j'essaie sans cesse d'obtenir est une bonne documentation. J'espère en avoir produit un peu moi-même. Mais il n'y a pas de sujet où je rencontre davantage de résistance que la création d'une bonne documentation. Personne n'a jamais le temps d'en créer, mais d'une façon ou d'une autre, ils arrivent à trouver des ressources pour payer le prix quand ils ne l'ont pas. Si obtenir de la bonne documentation est difficile dans le monde des entreprises, quid du monde des Logiciels libres ? C'est tout aussi difficile. Je ne peux pas compter le nombre de fois où j'ai essayé d'accéder au système d'aide pour l'une de mes applications KDE, pour n'arriver qu'à un message m'informant qu'il n'y a pas d'aide disponible. Parfois, vous avez vraiment l'impression que l'on vous dit : « Nous l'avons écrit, à vous maintenant d'essayer de comprendre ce qu'il faut en faire. » Une partie de la raison de cela est que, à mon avis, nous n'y réfléchissons pas comme il faudrait. |
| |
| Je commencerai par faire la distinction entre deux sortes de documentation : la documentation technique et celle faite pour l'utilisateur final. Comme son nom l'indique, la documentation technique est le genre de truc que pourraient fournir les développeurs, s'ils voulaient bien le faire. Cela pourrait aller au plus profond de la documentation du code, mais même à des niveaux plus élevés, ce n'est pas de la documentation pour utilisateur final. Reste la question de son existence même. Les développeurs aiment bien développer, mais ils n'aiment pas faire de la documentation. Et dans le monde des Logiciels libres, beaucoup de ces gens sont des bénévoles. | Je commencerais par faire la distinction entre deux sortes de documentations : la documentation technique et celle faite pour l'utilisateur final. Comme son nom l'indique, la documentation technique est le genre de truc que pourraient fournir les développeurs, s'ils voulaient bien le faire. Cela pourrait aller au plus profond de la documentation du code, mais même à des niveaux plus élevés, ce n'est pas de la documentation pour utilisateur final. Reste la question de son existence même. Les développeurs aiment bien développer, mais ils n'aiment pas faire de la documentation. Et dans le monde des Logiciels libres, beaucoup de ces gens sont des bénévoles. |
| |
| **But the topic of end-user documentation takes us in a different direction, and one where people with the right skills can be very helpful. It can also be a little frustrating. I recall one experience I had where I offered to help create end-user documentation for an application. When I asked to see what they had, the response was “We don’t have anything, that is what we want you to do.” Now I like to think I am a good writer, and I know I have been praised at work for the documentation I have written, but any writer needs something to start with. At work, I can make the technical people sit down with me, answer my questions, and so on. And you really need something like that to do good documentation. Good technical documentation can get you started, but to do good end-user documentation you will need to have some kind of access to the developers. And if the folks on the project you want to help don’t understand this, you need to explain it to them. They may want someone to come along and just magically make something happen without anyone else on the project being involved, but that is just not feasible. Good documentation is a group effort, really.** | **But the topic of end-user documentation takes us in a different direction, and one where people with the right skills can be very helpful. It can also be a little frustrating. I recall one experience I had where I offered to help create end-user documentation for an application. When I asked to see what they had, the response was “We don’t have anything, that is what we want you to do.” Now I like to think I am a good writer, and I know I have been praised at work for the documentation I have written, but any writer needs something to start with. At work, I can make the technical people sit down with me, answer my questions, and so on. And you really need something like that to do good documentation. Good technical documentation can get you started, but to do good end-user documentation you will need to have some kind of access to the developers. And if the folks on the project you want to help don’t understand this, you need to explain it to them. They may want someone to come along and just magically make something happen without anyone else on the project being involved, but that is just not feasible. Good documentation is a group effort, really.** |
| **In writing for the end-user, you need to be able to think a little differently. End-users are, by-and-large, not technical. There can be exceptions to this rule, but this is a good starting place for writing the most useful documentation. And the best way to do this is by thinking of “stories”. The Agile community tends to do a good job of this in terms of software development, but you need to carry this into documentation as well. You could write a book on this topic, and I don’t have that kind of space here so I will be somewhat more brief. Stories in this context means picturing a typical user of some kind, and imagining how they might try to use the software. Who is this person? Be specific – give this person a name, an age, a sex, a background. The better you do this – the better able you will be to get into this person’s skin and see things the way they do. Then look at some questions they might have.** | **In writing for the end-user, you need to be able to think a little differently. End-users are, by-and-large, not technical. There can be exceptions to this rule, but this is a good starting place for writing the most useful documentation. And the best way to do this is by thinking of “stories”. The Agile community tends to do a good job of this in terms of software development, but you need to carry this into documentation as well. You could write a book on this topic, and I don’t have that kind of space here so I will be somewhat more brief. Stories in this context means picturing a typical user of some kind, and imagining how they might try to use the software. Who is this person? Be specific – give this person a name, an age, a sex, a background. The better you do this – the better able you will be to get into this person’s skin and see things the way they do. Then look at some questions they might have.** |
| |
| Quand vous écrivez pour l'utilisateur final, il faut pouvoir réfléchir un peu différemment. Les utilisateurs finaux ne sont pas, en général, portés sur les choses techniques. Il peut y avoir des exceptions à cette règle, mais ceci est un bon point de départ pour écrire la documentation la plus utile. Et la meilleure façon de faire est de penser à des « histoires ». La communauté Agile le fait souvent très bien en termes de développement de logiciels, mais il faut porter l'idée vers la documentation aussi. Vous pourriez écrire un livre entier à ce sujet et je n'en ai pas la place ici ; je serai donc un peu plus bref. Les histoires dans ce contexte supposent la visualisation d'un utilisateur moyen en imaginant comment il pourrait vouloir utiliser ce logiciel. Qui est cet individu ? Soyez précis - donnez-lui un nom, un âge, un sexe, des antécédents. Mieux vous faites ceci et mieux vous saurez rentrer dans la peau de cet individu et voir les choses comme il les voit. Ensuite, regardez quelques questions qu'il pourrait avoir. | Quand vous écrivez pour l'utilisateur final, il faut pouvoir réfléchir un peu différemment. Les utilisateurs finaux ne sont pas, en général, portés sur les choses techniques. Il peut y avoir des exceptions à cette règle, mais ceci est un bon point de départ pour écrire la documentation la plus utile. Et la meilleure façon de faire est de penser à des « histoires ». La communauté Agile le fait souvent très bien en termes de développement de logiciels, mais il faut porter l'idée vers la documentation aussi. On pourrait écrire un livre entier à ce sujet et je n'en ai pas la place ici ; je serai donc un peu plus bref. Écrire des histoires dans ce contexte suppose de dépeindre un utilisateur moyen en imaginant comment il pourrait vouloir utiliser ce logiciel. Qui est cet individu ? Soyez précis - donnez-lui un nom, un âge, un sexe, des antécédents. Mieux vous faites ceci et mieux vous saurez rentrer dans la peau de cet individu et voir les choses comme il les voit. Ensuite, regardez quelques questions qu'il pourrait avoir. |
| |
| **Why would I want to use this software? | **Why would I want to use this software? |
| • The first example is a project called Miro (http://www.getmiro.com/), which produces software to download videos from the Internet and play them. I subscribe to a lot of video podcasts, as well as a few YouTube channels, and this is how I do it. And I use this software every day, so it is a good candidate for support. About a year ago they were looking to sign up people in a fund-raising drive called “Adopt a line of code”, for which you would pay $4 per month through PayPal. It looked good to me, so I signed up. After all, I get far more than $4 per month of benefit from this software and have come to rely on it every day.** | • The first example is a project called Miro (http://www.getmiro.com/), which produces software to download videos from the Internet and play them. I subscribe to a lot of video podcasts, as well as a few YouTube channels, and this is how I do it. And I use this software every day, so it is a good candidate for support. About a year ago they were looking to sign up people in a fund-raising drive called “Adopt a line of code”, for which you would pay $4 per month through PayPal. It looked good to me, so I signed up. After all, I get far more than $4 per month of benefit from this software and have come to rely on it every day.** |
| |
| Je vais donner quelques exemples tirés de mes propres expériences, afin de démontrer combien c'est facile de le faire, si vous êtes sensible au problème. Je me rends compte que cela peut prêter à penser que j'essaie de me donner bonne contenance, mais je ne crois pas être meilleur qui quiconque et je n'ai actuellement pas d'exemples d'autres personnes à portée de main. | Je vais donner quelques exemples tirés de mes propres expériences, afin de démontrer combien c'est facile de le faire, si vous êtes sensible au problème. Je me rends compte que cela peut prêter à penser que j'essaie de me donner bonne contenance, mais je ne crois pas être meilleur que quiconque et je n'ai actuellement pas d'exemples d'autres personnes à portée de main. |
| * Le premier exemple concerne un projet nommé Miro (http://www.getmiro.com/), qui fait des logiciels pour télécharger des vidéos sur le Net, puis de les lire. J'ai un abonnement à beaucoup de podcasts vidéo, ainsi qu'à quelques canaux sur YouTube et c'est comme ça que je le fais. J'utilise ce logiciel quotidiennement, ce qui en fait un bon candidat pour mon soutien. Il y a environ un an, ils cherchaient à faire inscrire des gens à une collecte de fonds appelée « Adopter une ligne de code » pour laquelle vous payeriez 4 $ par mois avec PayPal. Cela m'a semblé très bien, alors je me suis inscrit. Après tout, j'en tire un bénéfice de beaucoup plus de 4 $ par mois et je compte sur ce logiciel tous les jours. | * Le premier exemple concerne un projet nommé Miro (http://www.getmiro.com/), qui fait des logiciels pour télécharger des vidéos sur le Net, puis de les lire. J'ai un abonnement à beaucoup de podcasts vidéo, ainsi qu'à quelques canaux sur YouTube et c'est comme ça que je le fais. J'utilise ce logiciel quotidiennement, ce qui en fait un bon candidat pour mon soutien. Il y a environ un an, ils cherchaient à faire inscrire des gens à une collecte de fonds appelée « Adopter une ligne de code » pour laquelle vous payeriez 4 $ par mois avec PayPal. Cela m'a semblé très bien, alors je me suis inscrit. Après tout, j'en tire un bénéfice de beaucoup plus de 4 $ par mois et je compte sur ce logiciel tous les jours. |
| |
