Certains sites Web de documentation technique ont-ils un design très clair?
Je remarque des sites Web largement lus/importants, toutes les pages de documentation technique de mes exemples, ont un design vraiment vieux, terne et apparemment pauvre.
Est-ce exprès? Est-il basé sur des considérations ux?
J'imagine que les responsables de ces sites Web ont les ressources nécessaires pour construire un site Web plus agréable ou même avoir les compétences nécessaires pour le faire eux-mêmes, donc plutôt que d'en supposer qu'ils sont simplement paresseux, je me demande s'il y a une raison réelle pourquoi la conception est si simple. ? Et, s'il y a, alors je devrais le deviner pour des raisons UX (même si je n'ai aucune idée de pourquoi. Très peu de navigation/de recherche, sans codage de couleur, etc.).
Des suppositions?
Voici quelques exemples dont je parle:
GCC - https://gcc.gnu.org/install/configure.html
Une page aléatoire d'une commande Binutils Documents - https://sourceware.org/binutils/docs/ld/OptionS.html
Une page aléatoire de Linux Manpages - http://man7.org/linux/man-pages/man3/acl_calc_mask.3.html
Dans la conception, vous devez toujours demander: qui est l'utilisateur et quelle est son intention?
Avec les pages techniques "Manuel d'utilisation", l'utilisateur est probablement un ingénieur ou une sysadmin tente de trouver des informations aussi rapidement que possible afin d'obtenir quelque chose d'installer ou de fixer. Ils sont probables:
- Recherche de mots-clés
- Lire juste une section à la fois
- Ne pas utiliser son ordinateur/navigateur principal. Ils pourraient être sur une machine entière différente, lire la page sur un téléphone sans wifi, ni même lire à partir d'une impression du site Web.
Des choses qui vont devenir de la manière de cet utilisateur et entraveront les tâches:
- Beaucoup de navigation, étiquettes et liens qui déclenchent les mêmes mots de recherche
- Images de chargement lente, scripts et page "meubles"
- Beaucoup de formatage HTML portant la mise en oeuvre lorsqu'ils essaient de passer des messages directs de cette information à un collègue
Un autre utilisateur à penser sur ces pages est la personne qui les maintient. Leur travail est d'être précis et rapide. Leur travail n'est pas de connaître HTML et CSS en tant que concepteur Web de marketing.
Si vous regardez au-delà de l'esthétique, les pages sont très bien conçues pour ces utilisateurs - elles sont organisées de manière propre et hiérarchique avec des en-têtes de section, des tables appropriées et des listes.
Je suis incapable de poster cela comme un commentaire à l'une des autres réponses dus à la mauvaise réputation, mais que quelque chose à garder à l'esprit est que toutes les pages de documentation que vous avez liées sont destinées à être utilisées à partir de Text- seulement des interfaces. Il est donc logique que la documentation serait également dans le format de texte (principalement).
Le site de Manpages en particulier a été conçu pour ressembler exactement à une page man à partir d'un terminal UNIX, probablement, car il s'agit du format que les développeurs sont utilisés pour voir. Les autres, comme indiqué par Stacy H, sont conçus pour être interrogés par le texte. Ctrl+F est roi.
La documentation de code peut également être de style de style peu peu humanitaire, car elle est générée sur la procédure provenant de commentaires dans le code (à l'aide d'outils tels que Sphinx ) et n'a pas beaucoup d'attention portée à son apparence, mais il y a des exemples comme le - READTHEDOCS Thème conçu pour être plus convivial. Il est peut-être que la documentation ait été écrite il y a longtemps et que ce n'est que mis à jour au coup par temps, et dans le cas de la GCC, "il y a longtemps" prédire l'adoption généralisée de CSS/JavaScript. C'est un peu un meme que les développeurs détestent la documentation de la rédaction, il est donc possible que personne ne soit porté volontaire pour le mettre à jour (et ce sont des projets open-source, donc un effort de bénévolat serait nécessaire).
Bjarne Stroustrup a donné la réponse canonique à cette question. Citant de la FAQ sur sa page d'accueil :
Q: Pourquoi ne faites-vous pas votre site Web moderne?
A: Je suis un "fournisseur de contenu" et non un concepteur de site Web. Je peux utiliser mon temps pour améliorer le contenu ou les regards, mais pas tous les deux.
Ce qui semble "cool et moderne" à une personne est souvent considéré comme un mauvais goût par quelqu'un d'autre, et les modes changent vite. De plus, des téléchargements HTML très simples et affichent plus vite que toute autre chose, et de nombreuses personnes souffrent toujours de connexions Web lentes.
Le Q & A n'a pas été changé au cours de la dernière décennie ou deux. Il utilise un UI conçu il y a environ 4000 ans: Script alphabétique. Cet interface utilisateur a généralement été trouvé utile et est considéré comme intemporel par beaucoup.
Pour l'exemple Linux Spécifiquement, la documentation d'origine pour UNIX a été conçue pour être imprimée sur papier, puis de son retour, les terminaux graphiques étaient trop utiles pour afficher des graphiques pour "les déchets", vient de montrer du texte. (Et vous n'avez pas perdu de temps à plusieurs reprises Imprimer la documentation sur une imprimante abordable produite sur une page d'une page par minute - vous avez gardé la copie imprimée quelque part que vous pouvez le trouver!)
Toute personne qui apprise Unix de retour dans les années 1980 (qui m'incline) est très familière avec la disposition originale des pages de l'homme qu'ils font souvent référence et "Améliorer" la conception ralentit simplement l'expérience utilisateur de la recherche de Exactement ce que vous voulez regarder.
Une documentation technique telle que celle-ci est générée automatiquement par divers outils. Les Mangages sont un bon exemple de cela. L'entrée (qui est écrite par des humains) ressemble ceci :
.Dd March 23, 2002
.Dt ACL_CALC_MASK 3
.Os "Linux ACL"
.Sh NAME
.Nm acl_calc_mask
.Nd calculate the file group class mask
.Sh LIBRARY
Linux Access Control Lists library (libacl, \-lacl).
.Sh SYNOPSIS
.In sys/types.h
.In sys/acl.h
.Ft int
.Fn acl_calc_mask "acl_t *acl_p"
.Sh DESCRIPTION
... etc etc ...
L'objectif principal est de générer la documentation que vous obtenez lorsque vous exécutez la commande man sur la console. Quelqu'un a gêné un moyen d'utiliser la même entrée Gibberish pour générer une sortie HTML que vous pouvez afficher via un navigateur Web. Étant donné que la langue d'entrée a été conçue à l'origine pour la sortie de la console, elle ne prend pas en charge les types de choses dont vous auriez besoin pour générer une sortie Web riche. Même si ces fonctionnalités existaient, elles ne seraient pas utilisées, car l'utilisation principale de ces fichiers (l'utilitaire de console man) ne pourrait pas les utiliser. Certains manchages en ligne sont légèrement meilleurs que d'autres, mais au cœur, vous êtes toujours limité à la poignée d'effets de texte de base qu'un console peut gérer.
Votre lien Binutils est similaire. Vous pouvez voir la source d'origine pour cette page ici . La documentation est écrite en latex, qui peut être compilée pour de nombreuses formes de production différentes (HTML étant l'un d'entre eux). La documentation pour gcc utilise un système similaire.
Avec l'un de ces systèmes générant une documentation pour plusieurs formats de sortie, la sortie sera généralement limitée aux caractéristiques tout des différents formats de sortie. Dans de nombreux cas, ce sous-ensemble commun est extrêmement limité et vous obtenez une production assez simple.
Aussi, faites attention aux types spécifiques de logiciels que vous connaissez. C'est tout le logiciel de systèmes de bas niveau. Les personnes qui travaillent sur ce type de logiciel (moi-même incluse) ne vont généralement pas près d'une interface graphique. La conception de la documentation Web moderne et moderne n'est pas vraiment leur fond, et les personnes qui peuvent faire ce genre de chose ne sont pas généralement attirées par des projets de bas niveau comme celui-là. La "jolie" de la documentation que vous voyez est fréquemment pour un logiciel de niveau supérieur comme des cadres Web, où les développeurs sont plus susceptibles d'avoir une expérience avec ce type de chose.
Bien que de telles fonctionnalités ne soient pas encore utilisées aujourd'hui comme historiquement, de nombreux navigateurs permettent aux utilisateurs de configurer divers aspects de la manière dont les sites Web doivent être affichés, tels que les polices, les tailles et les couleurs à utiliser lors du rendu. Si un site Web ne définit pas explicitement aucun de ces traits, mais l'utilisateur d'un navigateur les définit à son goût, le contenu du site Web sera affiché de la manière dont l'utilisateur préférerait.
Pour qu'un site Web de prendre le contrôle de tels problèmes ait été une fois considéré comme une imposition du concepteur de site Web qu'il connaissait plus sur ce que le lecteur voudrait que le lecteur lui-même. Bien sûr, il est maintenant normal et attendu que les sites Web poussent une certaine "image", plutôt que d'essayer simplement d'afficher du texte de quelque manière que un utilisateur préfère, mais un tel comportement rend la vie plus difficile pour les utilisateurs qui peuvent par exemple. Avoir une mauvaise vision et avoir besoin d'utiliser des polices beaucoup plus grandes que la plupart des utilisateurs préféreraient. Certains concepteurs de sites Web comprennent que s'il n'y a aucune raison de ne pas accepter le style de l'utilisateur choisi par défaut, ils devraient simplement utiliser ce style.
parce qu'ils ont été conçus pour être lus sur un terminal
les pages de l'homme sont conçues pour être affichées dans un terminal. En tant que tel, il existe un ensemble de formatage très basique disponible. Vous pouvez lire sur le format sur ROFF (7) , mais votre cible était essentiellement une borne ou une imprimante. Il y a quelques formatage disponibles, mais vous ne pouvez pas compter sur la codage de couleur quelque chose que je vais lire sur un lien Telnet (je n'ai pas de chance?) Sur mon écran de phosphore monochrome.
Vous pouvez lire sur les en-têtes et les conventions utilisées des pages d'homme à pages manuelles (7) . Cela fournit une cohérence même si elles sont généralement développées par des personnes complètement différentes.
Info (5) Format Fournit des options quelque peu plus nombreuses, et vous trouverez de longs manuels dans ce format, par opposition aux pages de l'homme qui correspondent à une seule page. La documentation GCC et Binutils est en fait écrite Texinfo , à partir duquel elle est ensuite compilée dans différents formats: homme, info, html, pdf, etc.
C'est en fait depuis que les développeurs peuvent l'écrire une fois et avoir le même contenu sur plusieurs formats. Il vaut mieux ne pas avoir besoin de conserver les versions de plusieurs documents synchronisés (certains projets font, cependant). Le GNU projet indique que la documentation doit être disponible en format d'information, ce qui conduit à sa prévalence.
Vous pourriez avoir des thèmes différents appliqués, mais vous êtes limité par la structure réelle du contenu réel sous-jacent. Certains projets choisissent de ne pas faire de pages d'homme/d'information disponibles, telles que 7-Zip dont les documents sont en HTML. Je trouve que cela agaçant, mais cela peut être juste parce que je suis habitué à trouver le manuel des utilitaires directement à partir du terminal. De nos jours, il est courant d'être connecté à Internet, mais il n'a pas été utilisé pour l'être. De plus, accédant à la page manuelle du système actuel - que je peux être connecté via SSH, donc aucune image fantaisie- signifie que le manuel de la version que vous avez actuellement installée, et non une version future ou une autre saveur. Comparez SED vs sed vs SED vs SED vs SED .
Enfin, vous devez prendre en compte que la documentation technique est généralement faite par les développeurs. Ce qui signifie que la documentation technique est, bien, technique, dans le but de communiquer quelques points de sélection, tels que les paramètres qu'elle prend en charge. Il est bon d'être cohérent et familier aux développeurs. Donc, les cloches et les sifflets ne seraient pas appropriés.
Notez que les manuels d'informations montrent (en HTML) une structure de navigation. Ils peuvent ne pas comporter de moteur de recherche (cette fonctionnalité nécessiterait une prise en charge côté serveur, tandis que les fichiers générés peuvent être juste décompressés dans un chemin Web), mais ils offrent une version à une page, où vous pouvez facilement Ctrl-F à partir de votre utilisateur. Agent tout terme souhaité.
Le grand aimé et grandement détesté Site personnel de Richard Stallman's * est un exemple classique des présentations de vanilla. Il a probablement accès à et à la prise de conscience de la création/de présentation de site Web gratuite.
[.____] [* Chief gnuisance du GNU et de - Free Software Foundation Fame]
Bien qu'il s'agisse d'un site Web personnel, des parties de celui-ci seraient correctement décrites comme un "site Web de la documentation technique" et le style de présentation est cohérent.
[.____] Peut-être "naïf simpliste"? :-)
Ce n'est aucune erreur :-).
Richard a "un certain nombre d'axes à moudre" et il semble raisonnable de considérer le style de présentation comme étant destiné à "faire une déclaration".