Chez Jérémie - Mot-clé - documentation

MDN fait peau neuve

Jeremie — Sun, 12 Aug 2012 14:56:00 +0200

Après plusieurs mois de travail intense, la plateforme technique qui supporte MDN vient de changer. Originellement basée sur la solution DekiWiki de la société MindTouch, la documentation de Mozilla vient de passer sous une solution 100% maison : Kuma. Kuma est un projet codé à l’aide de Python/Django et est directement inspiré de la plateforme qui supporte déjà SUMO (le support utilisateur de Firefox) connu sous le nom de Kitsune.

Comme tous les projets Mozilla, Kuma est 100% open source. Le code est disponible sur GitHub et vous êtes largement invité à proposer patches et fixes si vous en avez envie

Le principal intérêt pour MDN de passer sur une plateforme ouverte et développée par Mozilla est simple : Pouvoir maîtriser les évolutions à apporter à la plateforme pour garantir la meilleure expérience utilisateur possible sur MDN. En la matière, les besoins sont importants et Mozilla a de grandes ambitions pour MDN.

Quoi de neuf ?

Si la plateforme, très jeune, souffre encore de quelques bugs en cours de résolution, les premières améliorations sont déjà visibles. Les deux plus évidentes sont liées à la localisation et aux templates personnalisés.

Concernant la localisation des contenus, disons-le clairement : on ne pouvait pas faire pire que ce qu’il y avait avant. Désormais, à chaque fois que vous voulez traduire une page, vous disposerez toujours de la version anglaise d’un coté et de votre propre version de l’autre, de même les liens entre les différentes versions localisées seront automatiques et vous avez même la possibilité de localiser l’URL de chaque page comme bon vous semble. La fonctionnalité la plus intéressante est liée à la navigation : lorsque vous naviguez sur une version locale de MDN (disons, le français par exemple) et qu’un contenu n’est pas disponible dans cette langue (souvent matérialisé par un lien rouge), vous accèderez automatiquement au contenu en anglais avec un bandeau vous proposant directement de traduire ce contenu.

Concernant les templates personnalisés, l’équipe de développement a créé un langage de script entièrement basé sur JavaScript (exécuté coté serveur) qui porte le nom de KumaScript. En clair, c’est du JavaScript avec quelques extensions pour en faire un langage de gabarit autonome (précédemment, il s’agissait d’un langage basé sur Lua, peu ou pas extensible). Les API disponibles restent encore sommaires, n’hésitez donc pas à ouvrir des bugs si vous avez des besoins particuliers. Ce système de template permet de créer des automatismes et des gabarits faciles à réutiliser d’une page à l’autre et il y a beaucoup à faire en la matière.

Et après ?

Dans les prochains mois, de nouvelles fonctionnalités vont faire leur apparition. La semaine dernière, toute l’équipe MDN (rédacteurs et développeurs) ainsi que quelques contributeurs se sont réunis à Toronto pour planifier et prioriser ces améliorations, 3 jours intenses sous la direction d’Ali Spivak, la nouvelle « Product Manager » de MDN. La listes de toutes les idées que nous avons amenées est beaucoup trop longue pour tout vous mettre ici… disons simplement que l’équipe de développement a du boulot pour plusieurs années si personne ne les aide

Parmi les principales priorités, les éléments suivant sont ressortis et vont faire l’objet d’un effort particulier dans les prochaines semaines/mois :

1. Sécurité

La plateforme étant encore jeune, certaines fonctionnalités ont besoin d’êtres sérieusement passées au crible des questions de sécurité. Ainsi, des filtres vont être appliqués ou améliorés pour rendre l’édition à la fois plus souple et plus sur (en particulier pour lutter contre les attaques de type CSRF), la politique de sécurité actuelle étant de tout interdire par défaut (script, iframe, etc. ne sont pas permis, même pour des usages légitimes). De même, l’envoi de fichiers n’est pour l’instant pas permis mais tout cela va rapidement changer.

2. Exemples de codes

Un travail de fond va être réalisé pour permettre aux utilisateurs d’embarquer des exemples de code actifs et modifiables (à la jsFiddle ou dabblet), le tout dans des conditions garantissant la sécurité des utilisateurs et des contenus. C’est sans doute le plus gros chantier des mois à venir (et celui que j’attends le plus impatiemment pour pouvoir déployer des exemples dans la doc SVG ;).

3. Localisation

Les outils pour la localisation vont être très largement améliorés (oui, c’est possible). Il s’agit d’un travail qui va s’étaler sur plusieurs mois (voire plusieurs années). Une des premières améliorations va être la possibilité de choisir la langue d’origine pour réaliser une traduction (aujourd’hui, c’est forcément l’anglais). Dans le même temps les bases d’un tableau de bord vont être posées pour permettre de plus facilement prioriser et planifier les pages à traduire.

4. API d’écriture

Pour le moment, Kuma n’offre qu’une API en lecture des contenus de MDN. Afin de rétablir le fonctionnement de certains outils et permettre le développement d’outils de consultation et d’édition tiers, une API permettant d’écrire du contenu dans MDN va être mise en œuvre. L’objectif est de permettre aux personnes voulant éditer du contenu avec leur éditeur de textes préféré de le faire ou bien de permettre à certains projets utilisant d’autres systèmes de wiki (GitHub par exemple) de partager leurs contenus facilement sur MDN (c’est typiquement le cas du projet JetPack pour Firefox).

5. Présence dans les moteurs de recherche

MDN souffre encore de certains manques qui grèvent son indexation par les moteurs de recherche. Les points les plus évidents vont être rapidement améliorés : qualité des méta-données (titre et description) et ajout d’un sitemap.

6. Recherche et tableau de bord

Un travail de fond va être engagé afin d’améliorer sérieusement la qualité des recherches sur MDN (techniquement parlant, cela va passer par le déploiement d’une base de données Elastic Search) et permettre de poser les bases techniques permettant de créer un véritable système de tableau de bord pour les éditeurs. Ce tableau de bord permettra dans un premier temps aux éditeurs de suivre et filtrer les contenus qui les intéressent pour, dans un second temps se transformer en un véritable système d’échange, de communication et de coordination (mais tout ça va prendre du temps, il va falloir être patient).

Mais encore…

Tout cela n’est que le début. Bien d’autre demandes ont été émises, parmi lesquels ont été priorisées les suivantes :

Localisation complète du système de tags
Possibilité de déplacer des ensembles de pages en une fois
Améliorer les liens croisés entre documentation et démos
Mettre en base de données, automatiser et partager les tables de compatibilité navigateurs
Améliorer le bandeau de localisation des articles non-traduit pour directement choisir la langue d’affichage alternative

Et bien plus encore… Si cela vous intéresse, vous trouverez toutes les notes de la semaine de travail sur ce Pad : https://etherpad.mozilla.org/MDN-Toronto-2012

Enfin, n’hésitez pas à ouvrir des bugs si vous avez des besoins ou des fonctionnalités que vous souhaiteriez voir dans MDN. L’équipe a profité de la réunion de la semaine dernière pour revoir son système de triage et de priorisation des bugs afin que leur traitement soit plus simple et plus compréhensible par tout le monde. L’opportunité de travailler sur un redesign de MDN a également été évoqué, cela fera l’objet d’un projet à part entière dans les prochains mois.

Ce n’est certes que le début et nul ne sait comment tout ça va évoluer, mais les choses sont bien engagées et MDN est bien parti pour devenir la documentation de référence du Web ouvert en étant désormais lui-même ouvert et accessible à tous. Je profite de l’occasion pour remercier chaleureusement toute l’équipe de développement de Kuma : Luke Crouch (groovecoder), Les Orchard (lmorchard), David Walsh (darkwing) et James Bennett (ubernostrum). Ils font un travail remarquable qui mérite d’être souligné.

Bonne documentation (^_^)

Bien démarrer avec MDN

Jeremie — Tue, 24 Apr 2012 21:12:00 +0200

Depuis maintenant 2 ans environ, je contribue activement à MDN (en particulier, j’écris la doc de la partie dédiée à SVG… en anglais pour l’instant) et depuis le début de l’année, j’organise tous les mercredis une petite soirée pour ceux qui veulent découvrir et aider à compléter la documentation du web ouvert chez Mozilla. A cette occasion, il y a un certain nombre de questions qui me sont posées régulièrement. En voici la liste avec les réponses qui vont bien.

Update : This article has been translate into English

Update 2 : Esteartículo fue traducido al castellano

C’est quoi MDN ?

Ne riez pas, vous n’imaginez pas le nombre de fois où j’ai entendu cette question.

Alors pour faire simple, MDN, c’est le “Mozilla Developer Network”. C’est un site web qui regroupe la quasi totalité de la documentation liée aux produits Mozilla. On y trouve 3 grandes sortes de ressources :

Des articles et des liens vers des ressources externes pour apprendre à utiliser les technologies du web
Des démos des dernières technologies implémentées dans les navigateurs modernes (Ces démo sont issues d’un concours mensuel, le “Dev Derby” organisé par John Karahalis)
Une documentation de références (API, balises, attributs, propriétés) des technologies Mozilla mais aussi et surtout de toutes les technologies du Web ouvert (HTML, CSS, Javascript, SVG, WebGL, etc.)

Cette dernière partie, la documentation des technologies Web, est la plus importante (autant en volume qu’en qualité) et celle sur laquelle, en ce moment, Mozilla porte ses plus gros efforts. Le point le plus notable de cette documentation c’est qu’elle est multi-navigateur avec des tables de compatibilité et des notes d’implémentation pour d’autres navigateurs que Firefox.

Même si cette documentation est sans doute une des plus riches documentations généralistes qui soit sur le Web, elle est loin d’être complète et c’est là que vous pouvez intervenir pour aider à la compléter

Est-ce que c’est compliqué de participer ?

Pas du tout, au contraire, c’est affreusement simple. C’est même sans doute un des points d’entrée les plus faciles pour contribuer chez Mozilla (vous n’aurez pas besoin de vous confronter à Bugzilla :-P).

En effet, pour contribuer à MDN vous n’avez besoin que de 2 choses :

Avoir envie
Avoir un compte utilisateur sur MDN

Et c’est tout.

L’opération la plus difficile consiste à trouver le bouton “Connexion” dans la barre d’en-tête, coincé entre le champ de recherche et l’horrible onglet blanc “Mozilla”… oui, au niveau ergonomie on a fait mieux. Cliquez sur ce bouton puis fournissez une adresse e-mail et un mot de passe (le système de connexion utilise le nouveau système Persona/BrowserID). Sur la page suivante, on vous demandera un “Nom d’utilisateur” qui sera le nom affiché en face de vos contributions. Et voila, vous êtes prêt à contribuer.

De son coté, la contribution est elle aussi très simple. Fondamentalement, MDN est à 80% un wiki. Sur toutes les pages du Wiki, une fois que vous êtes identifié, vous trouverez un bouton “Editer” (en haut à droite). Cliquez dessus, le contenu de la page se chargera dans un éditeur WYSIWYG (rassurez vous, si vous préférez vous la jouer hardcore, vous pouvez repasser en édition HTML). Faites-y les modifications que vous voulez, enregistrez (via le bouton “Sauvegarder” en haut à gauche) et voilà. Vous avez fait votre première contribution à MDN et au projet Mozilla en général : pas de processus de validation à la mords-moi-le-nœud, pas de délai de publication, pas de modération à priori (mais il y en a tout de même une, assez light il est vrai, à posteriori)… trop facile

Qu’est-ce que je peux faire, par où je commence ?

La réponse courte, c’est “par ce que vous voulez”, malheureusement, l’expérience m’a montré que cette réponse n’était pas celle attendue par les nouveaux venus.

Basiquement, sur MDN, vous pouvez faire 2 choses :

Proposer des démos via le “Dev Derby” mensuel, ce qui est une excellente façon de contribuer si vous êtes plutôt codeur.
Enrichir la documentation si vous vous sentez plutôt une âme de rédacteur

La contribution à la documentation peut prendre plusieurs formes qui vont dépendre du temps que vous êtes prêt à y passer et/ou de votre degré de motivation :

Écrire de nouveaux articles
C’est sans doute la contribution qui demande le plus de temps mais qui est aussi la plus utile au plus grand nombre. Notez que l’écriture de nouveaux contenus peut parfaitement se faire dans une autre langue que l’anglais
Traduire des articles existants
Ce n’est un secret pour personne, la partie anglaise de MDN est la plus fournie. Vous pouvez donc traduire ce que bon vous chante. Si vous avez envie mais ne savez pas quoi traduire, vous pouvez jeter un coup d’œil à la liste de l’ami Goofy.
Écrire des exemples de code
La littérature, c’est bien, des exemples concrets, c’est mieux. En général, un bon exemple vaut mieux que dix paragraphes d’explications complètement absconses. Écrire des exemples de code fait partie des contributions les plus utiles (et pas forcément les plus longues à produire) et MDN en manque cruellement (en particulier sur la partie SVG… je dis ça, je dis rien, hein).
Faire de la relecture
Comme MDN est faiblement modéré et comme l’erreur est humaine, il est toujours bon d’avoir des gens qui font de la relecture. Il peut s’agir aussi bien de relecture d’orthographe que de relecture technique. N’hésitez pas si vous avez peu de temps à consacrer car cela aidera beaucoup de monde (à titre d’exemple si vous lisez cet article, vous constaterez à quel point c’est désagréable de lire un texte bourré de fautes d’orthographe :-P).
Compléter les tables de compatibilité
MDN se veut une documentation agnostique du point de vue des navigateurs. En conséquence, il existe des tables de compatibilité sur de nombreuse pages de MDN. Elles permettent de savoir pour quel navigateur, une API, une balise, un attribut ou une propriété est disponible. C’est particulièrement utile et cela prend 5 minutes pour rajouter une information de compatibilité. C’est sans doute la façon la plus facile et la plus rapide de contribuer à MDN.

Et surtout, un dernier conseil. La documentation est quelque chose d’immense, en conséquence vous n’aurez jamais le temps de tout faire tout seul. Concentrez-vous donc sur les sujets qui vous intéressent vous personnellement. Dans mon cas, c’est SVG, mais chacun aura son propre centre d’intérêt. S’il y a un sujet en particulier qui vous intéresse, sachez que MDN dispose de “Topic Leaders” qui peuvent vous aider (n’hésitez pas à les contacter, ils sont là pour ça)

Et si vous êtes francophone allergique à l’anglais, sachez que vous avez de la chance. En effet, trois de ces “responsables” sont francophones : Moi-même qui peut vous aider sur tous les sujets liés à SVG, David Bruant pour toutes les questions autour de Javascript et Jean-Yves Perrier pour CSS (Jean-Yves est aussi employé Mozilla sur MDN, n’hésitez donc vraiment pas à le contacter)… Vous noterez qu’ils ne s’occupent que de technologies au rabais :-P

Sachez également qu’il existe 2 pages sur MDN qui complètent très largement ce que je viens de résumer ici :

La page “Pour commencer”
La page “A faire” (en)

Je veux traduire une page en français, comment je fais ?

Cette question est plus compliquée qu’il n’y paraît. En effet, l’actuel moteur de Wiki qui fait tourner MDN n’est pas très bien fichu sur la question de la localisation. Heureusement, d’ici quelques semaines, la plateforme technique devrait changer (les travaux sont en cours, mais vous savez comme ça se passe chez Mozilla : « on livre quand c’est prêt. — C’est à dire ? — Quand c’est prêt. »).

D’ici là, voici les principaux points auxquels il faut prêter attention.

Localiser les URL

D’abord un petit point sur la structure des URL de MDN. Elles sont de la forme :

https://developer.mozilla.org/locale/page/sous-page/sous-sous-page

Pour toutes les pages liées à une technologie, localiser l’URL reviendra, dans 90% des cas, à changer la locale. Exemple :

Néanmoins, vous pouvez parfois vous retrouver face à ça :

Dans ce cas il y a grosso modo 2 options :

Vous avez identifié une page manquante dans la partie française de MDN
Vous avez identifié une page que vous aimeriez traduire dans une partie de MDN qui n’est pas en français.

Dans le premiers cas, vous êtes le plus souvent tombé sur un lien qui mène vers une page qui n’existe pas (ils sont stylés en rouge). Dans ce cas, le travail de localisation du lien a déjà été fait et il vous faut juste trouver la page équivalente en anglais (ou autre, selon ce que vous parlez comme langue). En général, en remontant les arborescences, vous trouverez facilement une page qui a été traduite et qui vous permettra d’explorer l’équivalent de ce que vous cherchez dans la langue de votre choix. Notez que pour passer d’une langue à l’autre, vous avez sur les pages, en haut à droite un menu “Langues” qui permet de passer d’une version à l’autre d’une même page. J’y reviens ci-après.

Dans le deuxième cas, c’est parfois un peu plus délicat car vous aller devoir faire des choix de traduction des termes de l’URL. Ici, la difficulté va être de s’assurer qu’une traduction des termes n’a pas déjà été faite sur une autre page. L’idée c’est d’arriver à être cohérents d’une traduction à l’autre… ce qui est particulièrement critique pour les URL. Ici, la meilleure façon de procéder, c’est d’aller poser la question aux localisateurs qui sont rompus à l’exercice. Pour le français, le meilleur point d’entrée c’est le canal IRC #frenchmoz sur irc.mozilla.org ou éventuellement la mailing liste de la communauté francophone des contributeurs Mozilla. Tous les détails sont disponibles sur mozfr.org

Faire des liens croisés entre les différentes localisations

La deuxième difficulté lorsqu’on localise une page, c’est de réaliser des liens croisés entre les différentes versions d’une même page. Ces liens croisés apparaissent dans le menu “Langues” en haut à droite des pages.

Le seul problème, c’est que ces liens ne sont pas générés automatiquement. Concrètement, vous devez rajouter dans chacune des pages localisées les liens vers les autres localisations. Oui, ça veut dire que s’il y a déjà 10 versions différentes d’une page, vous aller devoir toutes les éditer une par une pour rajouter manuellement le lien vers la nouvelle version que vous venez de créer.

Ce n’est pas bien compliqué (c’est un petit bout de code normalisé en bas de page), mais c’est assez fastidieux

Bref, vivement le changement de plateforme technique.

Conclusion

Voilà, après ça, vous n’avez aucune excuse pour ne pas contribuer. Les problèmes de localisation mis à part (j’essayerai d’écrire un article sur le sujet quand on aura changé de plateforme) c’est facile et peu consommateur de temps. Si vous voulez en savoir plus, n’hésitez pas à passer dire bonjour le mercredi soir (je tiens une sorte de permanence dans les bureaux de Mozilla à Paris) ou à m’écrire (faites gaffe quand même, je réponds assez lentement). Au-delà de ça, d’autres peuvent vous aider si vous avez des questions sur la documentation : j’ai déjà cité les francophones David et Jean-Yves (aka Teoli)), mais chez les anglophones, vous pouvez facilement vous adresser à Eric Shepherd (aka Sheppy) et Janet Swisher. Vous pouvez facilement retrouver tout ce petit monde sur irc.mozilla.org sur la canal #devmo ou sur la liste de diffusion dev-mdc. Á noter que Jean-Yves, Eric et Janet sont les 3 principaux employés Mozilla chargés de superviser MDN, n’ayez donc aucun scrupule à vous adresser à eux (^_^)

La documentation c’est bon, mangez-en

MAJ du 25/04: Merci à Goofy pour la relecture orthographique

Documenter le Web ouvert, pourquoi et comment

Jeremie — Mon, 02 Jan 2012 09:00:00 +0100

Cela fait quelques temps que je m’implique dans plusieurs projets visant à documenter ou à fournir du matériel pédagogique concernant les technologies du web dit ouvert (standards et technologies sous licences open-source). De mon point de vue, cet effort de documentation est nécessaire pour plusieurs raison que je vais vous détailler ici et j’espère bien convaincre quelques-uns d’entre vous de me suivre sur ce long chemin… un peu aride, il faut bien l’admettre :-P

Pourquoi ?

En temps que « vieux » du Web (je créer des sites à titre personnel depuis 1997 et à titre professionnel depuis 2000), j’ai appris le Web « à la dure » en lisant quelques livres de qualité inégale, en utilisant outrancièrement la fonction « afficher la source » de mes navigateurs et en fréquentant divers forums de discussion. J’ai fait beaucoup d’erreurs (et je continue à en faire) mais en rencontrant les bonnes personnes et en apprenant de ces erreurs j’ai réussie à progresser pour arriver ou j’en suis aujourd’hui. Certes, je ne regrette rien, mais franchement ce n’était pas simple tout les jours et s’il est possible de se simplifier la vie, autant ne pas s’en priver.

Au delà de mes considérations personnelles et de mes propre besoins et envies, il y a tout de même quelques points notables qui militent en faveur d’une documentation plus importante et plus « normé » des différentes technologies Web.

Place aux jeunes

Je vois actuellement arriver une nouvelle génération de développeurs et d’intégrateurs Web. A mon grand désarrois, peu d’entre eux sont vraiment doués. C’est quelque chose d’assez normal, tout le monde ne peut pas être un génie. Mais le problème ne se situe pas là. Le problème est souvent bien en amont au niveau de leur formation. Malheureusement, il existe encore peu de cycles d’études qui forment vraiment aux technologies et problématiques propres au Web (en France, on est encore trop dans la dichotomie : écoles d’informatique d’un coté qui ne font que survoler les technologies Web sans en voir les aspects fonctionnels ; écoles d’art et de design de l’autre coté qui survolent vaguement les aspects fonctionnels en faisant totalement l’impasse sur les aspects techniques). Ainsi, la qualité de la formation dispensée dépend donc encore trop souvent de la qualité des professeurs et formateurs. La difficulté, c’est qu’eux même ont du mal à trouver des sources d’informations leur permettant de rester à jour. L’effort de veille à faire pour qu’un formateur reste au niveau est énorme et parfois difficile si l’on cherche du matériel pédagogique dans une langue autre que l’anglais. Pire ! De trop nombreuses sources d’informations sont parfois médiocres pour ne pas dire complètement fausse et le plus souvent peu ou pas mises à jour (le cas W3School, par exemple, a donné lieu à de vives réactions).

Avec tout ça, on voit bien qu’il est finalement, aujourd’hui encore, assez difficile de se former correctement aux technologies et techniques de mise en œuvre des sites Web.

La complexification des technologies

Les standards du Web sont quelque chose qui évolue en permanence. Depuis plus de 20 ans, ces technologies gagnent en maturité, changent, s’enrichissent et s’affinent. Depuis environs 3 ans maintenant, les choses vont même en s’accélérant. HTML5 change profondément la nature du langage HTML, CSS3 enrichie considérablement le nombre de propriétés disponibles, ECMAScript vient de passer en version 5 et la 6 est en préparation, etc. Le retour d’un univers concurrentiel sur le marché des navigateurs, l’émergence du Web mobile, tout cela contribue à rendre les technologies toujours plus complexes et à rendre leur implémentation parfois très hétérogène d’un navigateur à l’autre.

Quelques chiffres bruts pour se rendre compte :

HTML4 : 91 balises et 119 attributs -> HTML5 : environ 107 balises et plus de 143 attributs
CSS2.1 : 115 propriété -> CSS3 : près de 250 propriétés (C’est une estimation car les travaux de spécification ont à peine commencé)
SVG 1.1 : 80 balises et 267 attributs
Plusieurs centaines d’interfaces DOM (je n’ai pas eu le courage de compter)

Et encore, là, il ne s’agit que du sommet de l’iceberg des différentes technologies Web. Et puis, quid des implémentations ? Quel navigateur supporte quoi ? Et avec quel degré de précision/bugs ? Ou et comment trouver des informations pertinentes et à jour sur toutes ces technologies, leur fonctionnement et leurs interactions ?

Et puis tant qu’on en est à complexifier les choses, allons jusqu’au bout. La fonctionnalité suprême des navigateurs, le fameux « afficher la sources » et en train d’en prendre un petit coup dans l’aile. En effet, les techniques d’optimisation des performances (pour ne citer qu’elles) ont un petit effets de bords, elles ont tendance à rendre les codes sources illisibles par les êtres humains. Mais même sans ça, examiner le code source d’une bibliothèque Javascript de 200Ko est très loin d’être une partie de plaisir. Aujourd’hui, n’espérez donc pas apprendre sérieusement Javascript simplement en lisant du code (ce que j’ai pourtant fait il y a plus de 10 ans).

Contrairement à une idée reçu, le Web ce n’est pas simple. Je ne sais pas pour vous, mais s’il existe des sources d’informations fiables me permettant de m’y retrouver, ce sera avec plaisir que je les accueillerai.

Comment ?

J’en arrive donc à un constat simple : ressources de qualité douteuse + complexification des technologies = il faut rentrer dans une logique de documentation un peu plus sérieuse que ce qui a été fait jusqu’à présent.

L’initiative individuel

Jusqu’à une date très récente, l’effort de documentation des technologies du Web ouvert passait par des initiatives individuelles. Chaque développeur web ayant son propre site ou blog sur lequel il note et documente ce qui l’intéresse ou lui manque (c’est typiquement ce que je fais sur ce site ). Les plus fameux à ma connaissance sont sans doute :

Position is everything qui documente tous les bugs de Internet Explorer 6 (et 7) en matière de CSS (je ne compte plus les fois ou ce site m’a sauvé la vie)
Quirks mode de Peter-Paul Koch qui détail la compatibilité des propriétés CSS d’un navigateur à l’autre (on notera en ce moment le boulot que fait PPK sur le support des navigateurs mobiles)
A list apart et ce que l’on peut considérer comme son équivalent Français : OpenWeb qui produisent des articles à la fois précis et accessible à tous.

Il en existe évidement bien d’autre et il est impossible de les citer tous. Ceci étant, pour intéressant qu’il soit, cet effort de documentation reste encore très dispersé, peu structuré et nécessite de prendre le temps de chercher ce dont on a besoin tout en requérant une bonne dose d’esprits critique pour trier le bon grain de l’ivraie.

W3C et consort.

Deuxième source historique de documentation : le W3C et autre organisme de standardisation. C’est bête à dire, mais lire les spécifications des technologies peut être une mine d’or si l’on cherche des informations techniques précises. Malheureusement, il faut bien se le dire, les spécifications ne sont pas écrite pour le commun des mortels… en tout cas pas pour les développeurs Web. En effet, les spécifications sont de la matière brute. Elles sont écrite avant tout pour les fabriquant de logiciel (navigateurs, éditeur de code, etc.) et surtout, elles ne permettent pas de savoir quelles sont les différences d’implémentation d’un logiciel à l’autre. Leur lecture est donc rarement suffisante (et parfois même inutile… par exemple, essayer de lire la spécification d’ECMAScript pour apprendre le Javascript, c’est un peu comme regarder la formule chimique du beurre pour apprendre à faire un gâteau).

Saluons tout de même l’initiative du HTML Working Group qui, dans le cadre de HTML5, produit deux documents à destination des développeurs Web :

http://www.w3.org/TR/html5-author/ Version expurgé des spécificités purement techniques liées à l’implémentation de HTML et qui se concentre sur ce qui est vraiment utile pour les créateurs de sites Web.
http://dev.w3.org/html5/markup/ La liste détaillé de toutes les balises HTML5

Les fabricants de navigateurs

Une autre source de documentation parfois méconnus mais très riche existe : la documentation officiel des fabricants de navigateur. C’est vraiment dommage qu’elles ne soient pas plus connus car on y trouve parfois des perles :

MSDN : http://msdn.microsoft.com/
Documentation officiel de Microsoft, vous y trouverez absolument tout concernant les technologies implémentées dans Internet Explorer (et tout les autres produits Microsoft). Son seul vraie problème est d’être extrêmement mal structuré quand on l’aborde de l’extérieur (comprendre, via un autre moyen que les pages d’aide des produits Microsoft). Pour la petite histoire, les technologies Web, c’est là : http://msdn.microsoft.com/en-us/library/aa155073.aspx
MDN : https://developer.mozilla.org/
Site de documentation de Mozilla. Originellement fait pour documenter les technologies propres à Firefox, il est actuellement en train d’évoluer pour proposer une documentation agnostique sur tous les standards Web. En particulier, on y trouve la documentation de référence pour Javascript. Sa principale caractéristique est d’être un wiki éditable par tout le monde, c’est donc le lieu idéal pour y trouver (et y créer) la documentation dont vous avez besoin
Dev Opera : http://dev.opera.com/
On y trouve à la fois la documentation officiel des produits Opera, des articles des équipes d’Opera (chaque employé y a un blog pro.) mais également des articles écrits par des développeurs web indépendants. En effet, n’importe qui peut ouvrir un compte utilisateur et y écrire des articles.

La seul ombre au tableau, c’est le projet Webkit qui ne dispose pas d’une documentation officielle (en tout cas, je ne l’ai pas encore trouvée). On notera tout de même que depuis un peu plus de 1 an, les équipes de Google collabore avec Mozilla au sein de MDN pour que la documentation de référence soit la plus générique possible.

Le temps de l’action

Le fait est qu’on est encore loin d’avoir des documentations dignes de ce nom et, soyons claire, on n’est finalement jamais aussi bien servi que par soit même.

Aussi, je vous invite à écrire ce que vous savez. Il n’est pas nécessaire de faire de très long articles détaillés, mais simplement, mettre le résultat de vos expérimentations (à titre d’exemple, regardez ce que font Raphael Goetter avec IE7 no more ou la Web Agency Tympanus sur son blog). Quoi que vous en pensiez, ce sera toujours utile à quelqu’un (ne serais-ce que pour vous). Ok, ce que vous découvrez à peut-être déjà été écris ailleurs… mais ça n’a pas d’importance car plus il y a d’articles sur le même sujet, plus l’information est facile à trouver. Ne soyez pas timide, écrivez

Mais ce n’est qu’un début. Pour aller plus loin, je vous invite à regarder de près l’initiative Move the web forward qui détaille tout ce qu’il est possible de faire pour contribuer (au delà de la documentation) à améliorer le Web.

Enfin, et c’est là que les choses commence à se structurer, plusieurs organisations travaillent sur la documentation du Web ouvert. On notera en particulier deux acteurs majeurs de ce travail de documentation :

Mozilla

Depuis 2 ans environ, Mozilla a entamé un travail de fond visant à transformer MDN pour en faire une source de documentation neutre. Ainsi, pour tout ce qui concerne les standards du Web, vous y trouverez une documentation de référence pour les principaux langages (HTML, CSS, SVG, MathML, Javascript, etc.). L’objectif est, pour chaque balise, propriété, API, attribut, … de fournir une explication de comment ils s’utilisent avec des exemples, des cas d’usage, tout en documentant les spécificités liées aux implémentations de chaque navigateur.

Réaliser une telle documentation prend du temps et toute les bonnes volontés sont appréciées. Si vous voulez participer, vous n’avez rien d’autre à faire que de vous créer un compte utilisateur sur MDN et à écrire (c’est un Wiki rappelons-le). Si vous ne savez pas par quel bout commencer ou si vous pensez que vous n’êtes pas à la auteur pour participer, j’organise tous les mercredi une soirée de découverte de MDN dans les bureaux de Mozilla à Paris. N’hésitez pas à venir, même si c’est juste par curiosité, il y a à boire et à manger . Plus d’information sur la soirée de mercredi prochain : https://mercredidoc.etherpad.mozilla.org/4

W3C

L’été dernier, le W3C à lancé les Community Groups et un des premiers à avoir été créé fut le Web Education Community Group. Ce groupe a été créé à l’initiative de Chris Mills de chez Opera. Chris a proposé de partager le Web Standards Curriculum d’Opera sous licence libre. Il a donc été mis sur un Wiki dédié au W3C et désormais, tout le monde peu participer à son enrichissement. De manière plus général, ce Community Group à pour vocation de créer et promouvoir du matériel pédagogique à destination des professeurs et formateurs qui enseignent la création de sites Web.

Si vous êtes formateur ou enseignant vous devriez sérieusement envisager de participer à ce groupe. Contrairement aux groupes de travail sur les spécifications, la participation aux Community Groups est gratuite. En ce qui me concerne, je prévois de participer à la traduction Française du Web Standards Curriculum. Si vous voulez aider à faire cette traduction, laisser un message sur la mailing-list du groupe, je vous recontacterai alors pour qu’on se coordonne

Conclusion

La documentation du Web ouvert est un espace à défricher. Si vous voulez bénéficier d’une documentation de qualité, pour vous ou pour les autres, c’est à vous d’agir. Soyons claire, documenter est un travail long et ingrat dont on ne retire les fruits que plusieurs mois ou année plus tard. Ceci étant, il n’y a pas de secret, les projets qui marchent ce sont les projets qui bénéficient d’une documentation de qualité. C’est également vraie du Web et de la création de site. Retenez cependant 2 choses : Quelque soit votre contribution, aussi petite soit-elle, il y aura toujours quelqu’un pour vous en remercier un jour ; Si vous devez documenter quelque chose, documentez ce dont vous avez besoin pour vous-même, d’autre auront un jour ou l’autre le même problème que vous… la documentation est sans doute le seul domaine d’activité ou une action purement égoïste est également totalement altruiste