Documentation

Publié par le 14/02/2013 dans Bla Bla | 9 commentaires |

Pour une fois, je viens vers vous pour demander de l’aide :)

Certain(e)s le savent peut être, mais une partie de mon travail consiste à écrire de la documentation sur mon logiciel préféré, en l’occurrence des What’s New Guide (tous depuis une certaine version 3.2). Comme beaucoup, je trouve que des What’s new sont bien pour découvrir les nouveautés d’une nouvelle version d’un logiciel, mais quand on commence à chercher une fonction spécifique, on ne sait plus dans quel guide cela se trouve, sans compter que d’un guide à l’autre, des fonctions ont pu changer, autant dans l’ergonomie que dans l’organisation de l’outil. Bref, on est rapidement perdu.

Je suis actuellement (et depuis quelques temps…) en train d’écrire un guide de l’utilisateur complet, qui reprend tout le logiciel, avec autant les fonctions anciennes que les nouvelles et qui sera, à chaque nouvelle versions, mis à jour. Je ne vous cache pas que c’est un vrai marathon au vu de la quantité de choses à documenter et à prendre en compte… mais j’y tiens.

Donc, si je vous raconte tout cela, c’est pour avoir votre retour sur les documentations que vous avez déjà pu lire/consulter, que ce soit celle du logiciel que-je-ne-cite-pas-mais-vous-avez-bien-compris ou d’autres. Si vous avez le courage de répondre en commentaire à ces petites questions et d’ajouter tout autres commentaires, je vous en serais très reconnaissant :)

  1. Les documentations, est ce que vous les lisez ? Si ce n’est pas le cas, pourquoi ?
  2. La documentation doit être pour vous une description unique des fonctions (guide de référence) ou alors une explication plus approfondie des outils (Guide de l’utilisateur) ou plutôt un mix des deux ?
  3. Qu’est ce qui est impératif pour vous dans une documentation, mis à part les explications en elles-même : un index, une table des matières, un glossaire, de quoi prendre des notes ?
  4. La vidéo est partout et bon nombre (moi le premier), préfèrent souvent les didacticiels vidéos. Est-ce que ceux-ci peuvent se substituer à une documentation ou sont simplement un complément ? (N’oubliez pas qu’il y a des vidéos souvent officiel en ligne dans des classrooms qui sont déjà des compléments ;))
  5. Le format de la documentation.. ou plutôt le média : Est ce que vous souhaitez avoir un PDF, une version papier, une version pour tablette, une application autonome ? (ou un mix..)
  6. En parlant de papier, les documentations ne sont plus disponible au format papier. Comptez vous imprimer/faire imprimer/relier votre documentation ?

Merci de vos retours !

Edit : je précise que je parle bien de documentation officielle (donc en anglais) et non d’une initiative personnelle :)

Les tags : , , ,

    9 Commentaires

  1. Bonjour Thomas,
    J’ai vraiment autre chose à faire mais le sujet est super intéressant pour moi et en plus, si tu te lances dans cette nouvelle aventure t’aura bien besoin de te sentir suivi et/ou soutenu ;-)
    Alors, je te reponds très rapidement ci-dessous. Ce n’est pas exhaustif. Ce sont des avis personnels.

    Les documentations, est ce que vous les lisez ? Si ce n’est pas le cas, pourquoi ?
    - La réponse n’est pas simple… Est-ce la documentation papier ou numérique, est-ce l’ »officielle » ou la documentation en générale ? Et qu’entends-tu par « lire » ? Dans le cas d’une documentation « officielle » papier, la seule dont j’ai le souvenir d’avoir lu est celle de mon premier « vrai » logiciel de 3D. L’ensemble était constitué de nombreux livres qui faisaient environ 1,2 mètres de linéaires sur une étagère ! Les bouquins reprenaient chaque fonction une à une. Je l’ai lu de bout en bout. Sur les softs suivants, je ne l’ai plus fait. Et pour cause, la plupart du temps, les fonctions se ressemblent. Du coup, cela devient franchement fastidieux de se « lire » l’ensemble. Par contre, une bonne doc papier qui reprend exhaustivement chaque fonction et avec un super index est très confortable surtout dans sa langue maternelle ;-) Attention, c’est peut-être intéressant de réfléchir à l’impact environnemental avant de faire des documentations papier de trucs qui ne serviront qu’une fois type What’s new ?…

    La documentation doit être pour vous une description unique des fonctions (guide de référence) ou alors une explication plus approfondie des outils (Guide de l’utilisateur) ou plutôt un mix des deux ?
    - Pour moi, le mieux est un bon guide de référence associés à de bons tutoriels vidéos. C’est subjectif mais pour moi, un bon guide de référence est un livre qui reprend chaque fonction une à une qui en décrit l’usage de base et les conditions d’utilisations. Donne des exemples simples mais aussi des exemples plus pointus afin de montrer des idées d’utilisation de la fonction avec d’autres fonctions par exemple… Le tout soigneusement illustré ;-)

    Qu’est ce qui est impératif pour vous dans une documentation, mis à part les explications en elles-même : un index, une table des matières, un glossaire, de quoi prendre des notes ?
    - De la clarté, de la cohérence, de l’esthétique (faut penser au moral du gars qui finit par se résilier à ouvrir la doc après avoir passé 1 heure sur un p… de truc qui veut pas marcher :-) J’ai pas d’autres idées sous la main pour l’instant…

    La vidéo est partout et bon nombre (moi le premier), préfèrent souvent les didacticiels vidéos. Est-ce que ceux-ci peuvent se substituer à une documentation ou sont simplement un complément ? (N’oubliez pas qu’il y a des vidéos souvent officiel en ligne dans des classrooms qui sont déjà des compléments )
    - je me site : « un bon guide de référence associés à de bons tutoriels vidéos. » Mais perso, si je devais choisir, je choisirais un bon guide de référence plutôt qu’un bon tuto.

    Le format de la documentation.. ou plutôt le média : Est ce que vous souhaitez avoir un PDF, une version papier, une version pour tablette, une application autonome ? (ou un mix..)
    En parlant de papier, les documentations ne sont plus disponible au format papier. Comptez vous imprimer/faire imprimer/relier votre documentation ?
    - j’ai déjà un peu répondu au-dessus. Si j’ai un bon guide de référence et qu’il s’agit d’un soft sur lequel je bosse ou compte bosser à fond tous les jours, sans hésitation, j’imprime ou j’achète la version papier. Je lui fout des post-its, des coups de stabilo, Je peux le lire sans me bousiller les yeux. Je peux le balancer par la fenêtre… :-)
    Je préfère acheter un bouquin que d’imprimer moi même. Pour avoir l’équivalent d’un bouquin de 500 pages, il faut imprimer 2 ramettes A4 si on a pas de recto/verso. Et même avec, ça fait une ramette. Sans compter, la reliure…

    Et pour finir, je ne connais pas suffisament ZBrush pour dire si cela peut s’appliquer. Mais sur Maya ou Alias StudioTools, les documentations étaient séparées en plusieurs bouquins. Un pour les Nurbs, un pour les poly, un pour le rendering, un pour le texturing, etc… Et quand tu as la chance de les avoir tous sur tes étagères, c’est super confortable. Tu ne prends que la partie qui t’intéresse. Et comme généralement on a plutôt tendance à se spécialiser, on peut acheter ou racheter qu’une partie. De plus, ces docs étaient très bien faites. Je parle au passé. Cela fait longtemps que je n’ai plus mis le nez dedans.
    Dernièrement, j’ai lu le livre de Guillaume Gete sur MountainLion aux éditions Eyrolles (collection sans tabou). Je pensais juste le feuilleter histoire de me mettre à jour et passer le bouquin à mon fils. Mais en fait, il est tellement clair, aéré, pleins d’humour et d’astuces que j’en ai fait mon livre de chevet et l’ai lu de bout en bout !
    Voilà. Bonne journée et surtout bon courage ;-)
    Benoît
    P.S.: si tout le monde t’écrit de tel pavé et que tu les lis, tu n’es pas prêt de les sortir tes docs :-)

  2. Salut thomas.
    Alors par ordre des questions:

    1.Je les lis quand j’ai besoin d’une info bien precise sur une fonction,mais je ne lis pas toute la doc.
    2.Je prefere approfondie avec si possible un exemple concret des fonctions.
    3.une table des matieres dynamique.
    4.Pour moi,les videos sont tres souvant un substitue(d’ailleurs j’ai appris a me servir de cinema 4d ou zbrush uniquement avec des videos,dont les tiennent d’ailleurs!!!)
    5.A choisir,une application autonome serait pas mal.Une version pour tablette peut se contenter du format PDF,donc pas besoin d’un format specifique.
    6.Aucun des trois(se referer a la question 5).

    En esperant t’avoir aider.

  3. Hello,
    je ne réponds pas vraiment aux questions,
    mais pour moi la doc à fait un gros pas en avant quand elle a été directement intégrée à l’interface du logiciel. (comme zb et RealFlow)
    on clique sur l’outil avec un petit raccourci clavier, et hop, vraiment top.

  4. Hi….
    Bon je vais faire dans l’ordre
    1- les documents sont souvent en anglais (même si j’arrive a lire l’anglais dans les bd ou sous-titre)et utilise des termes généralement trop spécifique que je ne comprend pas et que les traducteurs ne connaissent pas… lorsque celles si sont en français elles sont souvent pas assez détaillé pour savoir utilisé le logiciel (manque de screen ou de précisions).

    2-je préfère généralement une simple description suivi d’une explication (illustré si possible).

    3- un index bien organisé suffit généralement.

    4-j’aime bien avoir une description général du logiciel sous la main histoire de savoir comment fonctionne les outils que j’utilise, je pars sur une vidéo que lorsque la description ne m’aide pas plus ou que je souhaite approfondir une fonction.

    5-j’aime le PDF on peux généralement faire une recherche dedans pour facilité la tache, il est également le format qui s’adapte au plus grand nombre de plate-forme différente..

    6-j’aime bien imprimer mes doc pour faire mes propres notes (avec post-it marqueur etc…)

    voila en espérant t’aider dans ta tache OH combien vital xD

  5. Salut Thomas,
    Je vois ta news et te félicite pour ton courage, écrire une doc ou un « what’s new » ne doit pas être de tout repos.

    1.Les documentations, est ce que vous les lisez ? Si ce n’est pas le cas, pourquoi ?
    Je les ais lu et même très attentivement pour mes 1er soft (3ds toshop ect ) durant mes études. La doc consultable en ligne, ponctuellement oui, mais jamais dans son ensemble, je préfère apprendre en regardant des vidéos car plus que de simple outils on nous montre aussi une mise en situation et des méthodes de travail (qu’il faut bien sur adapter selon ses goûts par la suite).

    2.La documentation doit être pour vous une description unique des fonctions (guide de référence) ou alors une explication plus approfondie des outils (Guide de l’utilisateur) ou plutôt un mix des deux ?

    Une bonne doc devrait être un mix des deux, mettant en avant un vrai guide de l’utilisateur avec à chaque outils utilisé un lien vers son explication approfondie.

    3.Qu’est ce qui est impératif pour vous dans une documentation, mis à part les explications en elles-même : un index, une table des matières, un glossaire, de quoi prendre des notes ?
    Un bon index pour atteindre facilement n’importe qu’elle section est essentiel, et comme l’as déjà dit Benoit, pourvoir prendre des notes, coller des post-it : s’approprier l’ouvrage pour s’approprier le soft (avec une version numérique ça reste bien compliqué comme pratique).

    4.La vidéo est partout et bon nombre (moi le premier), préfèrent souvent les didacticiels vidéos. Est-ce que ceux-ci peuvent se substituer à une documentation ou sont simplement un complément ? (N’oubliez pas qu’il y a des vidéos souvent officielles en ligne dans des classrooms qui sont déjà des compléments ;) )

    Halala, la vidéo, … c’est génial en soit y’a pas à dire. C’est visuel et auditif à la foi, c’est concret ( comme ton précédent atelier ) car ça ne tourne pas autour d’un simple sphere vide de sens. Mais ça ne peut pas répondre à toutes les questions hélas. La doc, quand on cherche une réponse très précise, ou que l’on veut sortir des sentiers battus des outils les plus usités devient indispensable il faut l’admettre.
    Pour moi il peut y avoir 2 cas :
    - on débute, on sait pas quoi faire : la vidéo s’impose pour prendre en main un soft.
    - on est (ou commence à être) un utilisateur confirmé, il devient très vite difficile de trouver une réponse dans le fourmillement de vidéo qui existe aujourd’hui.

    5.Le format de la documentation.. ou plutôt le média : Est ce que vous souhaitez avoir un PDF, une version papier, une version pour tablette, une application autonome ? (ou un mix..)
    Les versions papier n’existent plus ou presque plus donc ça serait PDF non ? Perso, j’aime bien les PDF mais la recherche d’info peut être un peu galère parfois.
    Une version tablette : pourquoi pas, mais tout le monde n’a pas une tablette chez lui ni au travail.
    Une appli … tu penses à quoi exactement ?

    Laquelle choisir ? Aucune idée à vrai dire, j’y fait pas assez référence pour te donner un avis vraiment efficace, mais le PDF semble être le plus courant ( les vieilles habitudes ont la vie dure).

    6.En parlant de papier, les documentations ne sont plus disponible au format papier. Comptez vous imprimer/faire imprimer/relier votre documentation ?

    Franchement, non.

  6. 1- Si ce sont bien des docs officielles dont on parle, je les consulte rarement et souvent en dernier recours, quand je n’ai pas trouvé ma réponse sur le net ( forum, didacticiels vidéos,.. )

    2- Pour moi, la doc idéale, ce serait un mix des 2. Du général au spécificités. Théorie, technique et cas concrets (avec des mini vids).

    3- L’impératif, pour ma part, c’est d’arriver rapidement à localiser le chapitre qui va traiter de mon problème. Donc un très bon outil de recherche, capable avec quelques mots clés de me localiser les bons chapitres.

    4- La vidéo reste pour moi le meilleur des supports pour apprendre un logiciel graphique. Dans le cadre d’une doc novatrice, je pense qu’il serait génial d’intégrer dés que possible des vidéos ( même super courtes ) pour illustrer les parties théoriques ou techniques. En tous les cas, ça m’engagerai plus souvent à consulter la doc.

    5- Perso, ma préférence va pour une application au format tablette. Je suis également pour des pages vivantes, aérées, illustrées et avec des codes couleurs!.. Rien qu’ça.

    6- Je crois qu’il y’a des toiles d’araignée dans ma Canon.

    PS: .. et pourquoi pas un site dynamique et interactif uniquement consacré à la documentation de ZBRUSH ( compatible mobile tablette écrans – fait avec Muse, par exemple- ).
    Roh, c’est juste pour amener un peu d’eau à ton moulin..
    Bonne continuation.

  7. Bonjour Thomas et encore Bravo pour ton travail!!! voici quelques réponses qui j’espère pourront t’aider.
    • Les documentations, est ce que vous les lisez ? Si ce n’est pas le cas, pourquoi ?
    - Non je préfère de loin les dictatiels vidéos trouvés sur le net car ceux ci ciblent généralement beaucoup mieux ce que je recherche. les documentations style Adobe Format Pdf sont soit trop terre à terre, ou ne couvrent pas à 100% les PB recherchés.
    • La documentation doit être pour vous une description unique des fonctions (guide de référence) ou alors une explication plus approfondie des outils (Guide de l’utilisateur) ou plutôt un mix des deux ?
    - J’aimerais que la doc soit une description généraliste des fonctions (Style infobulle ZB) et si toutefois l’utilisateur veut en savoir plus, un petit lien « en savoir plus » pointant sur quelques videos détaillant les effets de cette fonctions, voir ses astuces d’utilisations.
    • Qu’est ce qui est impératif pour vous dans une documentation, mis à part les explications en elles-même : un index, une table des matières, un glossaire, de quoi prendre des notes ?
    - Pour moi, une table des matières mais « intelligentes » j’entends par intelligente en plus de l’explication première pour celle-ci, nous donner quelques cas voir astuces pour utilisés cette fonctions,
    • La vidéo est partout et bon nombre (moi le premier), préfèrent souvent les didacticiels vidéos. Est-ce que ceux-ci peuvent se substituer à une documentation ou sont simplement un complément ? (N’oubliez pas qu’il y a des vidéos souvent officiel en ligne dans des classrooms qui sont déjà des compléments )
    -Je pense qu’il y a une hiérarchie de compréhension (je sais je dis totalement le contraire dans ma réponse à la question n°1…) Nous lisons une documentation dans un premier temps ca nous allons à tâtons lors de l’apprentissage d’un logiciel. Ensuite, nous recherchons des fonctions détaillées par la video pour savoir exactement comment procéder pour une fonction précise. donc les deux doivent vivre ensemble pour une doc.
    •Le format de la documentation.. ou plutôt le média : Est ce que vous souhaitez avoir un PDF, une version papier, une version pour tablette, une application autonome ? (ou un mix..)
    - Le must un PDF interactif contenant de la video, et pour les tablettes, la même choses, un iDocMagazine avec texte et video, et liens web pour compléter certaines compréhensions de fonctions.
    • En parlant de papier, les documentations ne sont plus disponible au format papier. Comptez vous imprimer/faire imprimer/relier votre documentation ?
    - Non pas de papier pour une documentation. d’une part une documentation doit cibler le coté pratique. et actuellement une documentation papier est moins pratique à utiliser pour l’apprentissage, disons moins rapide. Pour exemple je n’utilise plus d’encyclopédie car il y a Wikipedia.
    D’autre part le papier ne permet pas de jongler avec des liens vidéos ou des liens internet d’artistes expliquant tel ou tel fonctions.
    En résumé une doc doit être avant tout pratique, nous amenés droit à à l’info désirée et a ses astuces d’utilisations si possible.Une documentation interactive me paraît plus aisée pour ce genre d’emplois.

    En espérant que ca t’aidera!!

  8. Tout d’abord, merci à tous ceux qui m’ont répondu (y compris par email :)
    Le premier constat est qu’il y a de tout, dans l’usage, les besoins et les problèmes… J’ai pas terminé de m’arracher les cheveux :)

    Sinon, je précise qu’à l’heure actuelle, je suis plus dans le mix manuel de référence et de l’utilisateur. C’est à dire que j’explique les concepts, l’utilisation et ensuite, cela propose l’explication de toutes les fonctions/options.

    J’essayerai de vous mettre l’exemple des ZSpheres quand il sera corrigé en ligne, pour que vous ayez une idée (attention, gros pavé…)

  9. Bonjour, bien le webinar d’hier soir, merci encore.
    J’utilise Zbrush que depuis septembre 2012 et fait de la 3D sérieusement depuis seulement janvier 2011, mais je suis graphiste depuis 20 ans et des docs papiers, PDF, j’en ai lu. J’aime bien quand elles sont sous la forme de mini site/application online quand je suis chez moi.

    Voila ma petite contribution

    1. Personnellement je lis la doc au besoin ou quand je sèche sur une technique ou un outil.

    2. Explication approfondie de l’outil et variantes d’application. Des images d’exemple sont bien aussi.

    3. Un moteur de recherche pas trop lourd (très simple d’accès) et rapide s’il est en ligne.

    4.La vidéo est pour moi un complément et y faire référence dans la doc est un plus.

    5.Un mix, car on set pas toujours devant sont ordi à la maison…

    6.Jamais, numérique, numérique.

    A la prochaine

    Etienne

Répondez

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Vous pouvez utiliser ces balises et attributs HTML : <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>