Souvent, quand on veut se documenter sur un logiciel, on est intéressé seulement par faire une chose bien précise. Un manuel, qui s'apparente à un livre, c'est plutôt fait pour être lu du début à la fin.
Ce que tu décris correspond au comportement ou au besoin des utilisateurs qui ont déjà le logiciel en main. Pour découvrir un nouveau logiciel, ses concepts et appréhender son utilisation, un texte linéaire convient très bien.
D'ailleurs un manuel de logiciel bien écrit n'est pas conçu pour être lu du début à la fin. Par exemple le TeX book (le manuel de TeX) est découpé en chapitres, chaque chapitre a trois niveaux de profondeurs: la lecture linéaire du premier niveau de profondeur de chaque chapitre permet de découvrir le logiciel et ses différents concepts, chaque chapitre est consacré à un sujet bien défini dont la lecture des profondeurs supérieures va révéler tous les aspects. Associée à un index de qualité cette organisation est très efficace!
Un autre exemple est le couple Perl avec d'un coté le livre de Larry Wall (pour la prise en main) et de l'autre le cookbook qui présente tout un tas d'aspects pratiques du langage, en répondant à des questions du type «comment je fais ...» À eux deux ces livres font une documentation excellente pour Perl.
C'est pour ça qu'une documentation orientée « topiques » est souvent plus simple pour l'utilisateur.
(Une documentation organisée par sujets? un manuel de référence?)
À condition d'être familier avec les concepts du logiciel: par exemple, toute organisée par sujets qu'elle soit, la documentation de MS-Windows m'est toujours restée hermétique parcequ'elle explique comment «paramétrer le schéma de stratégie pour les utilisateurs locaux» sans avoir auparavant présenté la position de ce schéma dans l'organisation du système (je suppose qu'il existe aussi un livre pour ça).
Le manuel de GNU Make a le même genre de défaut car il ne donne pas vraiment de vue d'ensemble de l'utilisation du programme mais se décrit tous les détails du programme, sujet par sujet: c'est un manuel de référence mais pas un guide d'introduction.
Dans les trois types de documentation de logiciels (introduction, référence, fiches de recettes) les trois ont leur raison d'être et leur public, et un logiciel qui n'a pas ses trois la n'a pas une documentation complète.
[^] # Re: Documentation orientée topiques
Posté par Michaël (site web personnel) . En réponse à la dépêche Scribus : nouveau manuel libre. Évalué à 7.
Ce que tu décris correspond au comportement ou au besoin des utilisateurs qui ont déjà le logiciel en main. Pour découvrir un nouveau logiciel, ses concepts et appréhender son utilisation, un texte linéaire convient très bien.
D'ailleurs un manuel de logiciel bien écrit n'est pas conçu pour être lu du début à la fin. Par exemple le TeX book (le manuel de TeX) est découpé en chapitres, chaque chapitre a trois niveaux de profondeurs: la lecture linéaire du premier niveau de profondeur de chaque chapitre permet de découvrir le logiciel et ses différents concepts, chaque chapitre est consacré à un sujet bien défini dont la lecture des profondeurs supérieures va révéler tous les aspects. Associée à un index de qualité cette organisation est très efficace!
Un autre exemple est le couple Perl avec d'un coté le livre de Larry Wall (pour la prise en main) et de l'autre le cookbook qui présente tout un tas d'aspects pratiques du langage, en répondant à des questions du type «comment je fais ...» À eux deux ces livres font une documentation excellente pour Perl.
(Une documentation organisée par sujets? un manuel de référence?)
À condition d'être familier avec les concepts du logiciel: par exemple, toute organisée par sujets qu'elle soit, la documentation de MS-Windows m'est toujours restée hermétique parcequ'elle explique comment «paramétrer le schéma de stratégie pour les utilisateurs locaux» sans avoir auparavant présenté la position de ce schéma dans l'organisation du système (je suppose qu'il existe aussi un livre pour ça).
Le manuel de GNU Make a le même genre de défaut car il ne donne pas vraiment de vue d'ensemble de l'utilisation du programme mais se décrit tous les détails du programme, sujet par sujet: c'est un manuel de référence mais pas un guide d'introduction.
Dans les trois types de documentation de logiciels (introduction, référence, fiches de recettes) les trois ont leur raison d'être et leur public, et un logiciel qui n'a pas ses trois la n'a pas une documentation complète.