Documentation

Canonical crée l'Open Documentation Academy

Soumis par fredericmazue le

Canonical annonce la création de l’Open Documentation Academy. L'objectif est de transformer la documentation en créant et maintenant un produit et une pratique de documentation qui représenteront un standard de référence dans l’open source. 

L'Open Documentation Academy associe l'équipe de documentation de Canonical à des débutants en documentation, des experts et des personnes se situant entre les deux, afin d’aider à améliorer la pratique de la documentation et à devenir de meilleurs rédacteurs.

Pour les débutants, ils bénéficieront d'aide, de conseils, de mentorat et une centaine de tâches différentes à entreprendre. Les experts pourront, grâce à ce lieu de partage des connaissances, s'impliquer dans de nouveaux développements et échanger sur leurs propres projets.

L'un des principaux objectifs de cette initiative est de contribuer à réduire les obstacles à une contribution réussie aux logiciels open source, en faisant de la documentation la porte d'entrée.

L'Open Documentation Academy comprendra un programme structuré de soutien et de développement pour les participants, leur permettant de faire leurs premiers pas et d'acquérir la confiance nécessaire pour mener leurs propres initiatives en matière de documentation.

Pour démarrer, l'Open Documentation Academy propose une liste de tâches documentaires. Il suffit d’en choisir une et de commencer. Les tâches comprennent le test et la correction des tutoriels, la mise à jour des documents obsolètes, la restructuration des documents volumineux et tout ce que vous voudrez suggérer. Notre liste s'allonge, et l'Academy veillera à ce qu'il y ait toujours un large éventail de tâches disponibles, dans le plus grand nombre possible de projets et de technologies. Les contributeurs seront guidés dans leurs premières contributions, et conseillés sur les approches à adopter.

Canonical possède une équipe expérimentée d'auteurs techniques dédiés à ses projets majeurs. Ces projets englobent un large éventail allant de la sécurité aux commandes en ligne, en passant par à l'orchestration du cloud et au provisionnement des appareils. L’équipe de Canonical travaille dans un cadre commun appelé Diataxis.

La liste de tâches est désormais ouverte et ne cesse de s'allonger, le guide de démarrage permet de connaître les prochaines étapes. Il existe un forum de discussion sur Ubuntu Community Hub.

JetBrains WriterSide : un outil pour écrire des documentations technique

Soumis par fredericmazue le
IDE

Avec WriterSide, le célèbre éditeur Jetbrains entend proposer aux rédacteurs et développeurs un outil intégré à ces différents IDE pour écrire de la documentation technique, à l'aide d'un workflow d'écriture, de test et de construction.

L'outil met un place un pipeline 'doc as code'. Concrètement, sur la base d'outils de développement tels que Git, des revues pull et des contrôles automatisés, WriterSide permet à toute l'équipe de contribuer, de réviser et de suivre les modifications comme elle le fait avec le code. 

JetBrains souligne que WriterSide est construit par des documentaristes, pour des documentaristes. Ce projet s'est développé à partir de centaines d'entretiens clients et de plus de 10 ans de travail sur la documentation de la plateforme IntelliJ. Ces expériences nous ont donné une longue liste de fonctionnalités à construire et de problèmes à résoudre, précise encore JetBrains

WriterSide prend en charge à la fois Markdown et un balisage personnalisé basé sur XML et permet de combiner les deux formats dans le même document. WriterSide veut garantir la qualité et l'intégrité de la documentation avec plus de 100 inspections à la volée dans l'éditeur ainsi que des tests dans la prévisualisation et pendant la construction. Il dispose d'une fonctionnalité d'aperçu qui montre les documents exactement tels les lecteurs les verront. La fonctionnalité permet de prévisualiser une seule page dans l'EDI ou d'ouvrir l'intégralité du site Web d'aide dans un navigateur.

Site : jetbrains.com/writerside

Open Web Docs : un projet de documentation des plates-formes Web

Soumis par fredericmazue le

Open Web Docs est un collectif de personnes et d'organisations qui estiment qu'une documentation Web bien entretenue est une infrastructure numérique essentielle qui offre d'immenses avantages sociaux et économiques.

Open Web Docs a été créé pour garantir l'intégrité à long terme de la documentation de la plate-forme Web sur des ressources standards de facto telles que MDN Web Docs de Mozilla, indépendamment de tout fournisseur ou organisation. Plutôt que de créer de nouveaux sites de documentation, Open Web Docs s'engage à améliorer les plateformes existantes grâce à ses contributions. 

Le personnel d'Open Web Docs est soutenu par les sponsors fondateurs Coil, Google et Microsoft, avec un soutien financier supplémentaire d'Igalia et des bailleurs de fonds sur Open Source Collective. Mozilla, Samsung et le W3C fournissent une assistance et une participation supplémentaires.

Les priorités 2021 du projet incluent la collaboration avec les rédacteurs et ingénieurs MDN de Mozilla pour prendre en charge la récente transition d'infrastructure et pour prioriser et aller de l'avant avec les travaux de documentation clés, développer une communauté de contributeurs autour de la documentation de la technologie Web de base, des données de compatibilité des navigateurs et améliorer la documentation JavaScript.

Open Web Docs devrait bientôt annoncer des embauches.

Site : opencollective.com/open-web-docs

Rust 1.48

Soumis par fredericmazue le

L'équipe Rust de la fondation Mozilla a publié une nouvelle mouture de son langage maison, tout rouillé à l'état natif : Rust 1.48. Cette mouture apporte, conformément à la tradition des changements dans la bibliothèque, et de nouvelles API. Mais l'équipe met tout particulièrement en avant les évolutions de rustdoc, l'outil de génération de documentation.

Jusqu'à présent il n'était pas possible, en documentant un type, d'établir un lien avec d'autres types pouvant être utilisés de concert avec lui. Dans cette version, vous pouvez utiliser une syntaxe pour informer rustdoc que vous voulez créer un lien vers un type, et il générera les URL pour vous. Cela permet aux utilisateurs de la documentation de naviguer facilement d'un type à l'autre.

De plus Vous pouvez désormais spécifier #[doc(alias = "<alias>")]sur les éléments afin d'ajouter des alias de recherche lors de la recherche. Cela ressemble à ceci :

#[doc(alias = "bar")]
struct Foo;

Avec cette annotation, si l'on donne "bar" dans la recherche de rustdoc, Foo apparaîtra dans les résultats, même si le texte de recherche ne contient pas "Foo".

Ponicode dévoile GitHub Action Ponicode Dogstring pour Python

Soumis par fredericmazue le

Ponicode étend sa suite de solution à la documentation avec Github Action Ponicode Dogstring. Cette GitHub Action pour les projets Python permet aux développeurs de documenter les fonctions de leur code automatiquement, en générant une docstring pour les fonctions Python.

Github Action Ponicode Dogstring pour les projets Python permet de :

  • S’engager pour un code propre et partageable : la documentation automatisée grâce à cette nouvelle fonctionnalité de Ponicode permet d’assurer la qualité du code et de fluidifier la collaboration sur des projets.
  • Garder le contrôle de son code : cette fonctionnalité ne s’applique qu’aux fonctions Python ne possédant pas de docstring afin de préserver le travail des développeurs qui peuventt ainsi décider librement d’incorporer les suggestions de Ponicode Dogstring dans leur code ou non.

Actuellement disponible en version bêta (0.1), Ponicode a pour objectif de couvrir plus de langues et d’améliorer l’expérience utilisateur au fil du temps.

Site et démonstration en ligne : api.ponicode.com/dogstring

OpenAPI Comment Parser : un outil IBM pour analyser les commentaires dans le code d'une API et générer la documentation correspondante

Soumis par fredericmazue le

Les développeurs ont besoin d'instructions sur la façon d'utiliser une API et ils ont besoin d'un moyen de l'essayer. Une bonne documentation satisfait ces deux besoins. Pour aider à générer une telle documentation, conforme aux spécifications OpenAPI, IBM propose OpenAPI Comment Parser

OpenAPI Comment Parser a pour objectif de donner aux développeurs d'API un moyen de générer une documentation conforme aux spécifications OpenAPI à partir de commentaires en ligne dans leur code. Lorsque la spécification OpenAPI vit dans le code, les développeurs sont beaucoup plus susceptibles de la maintenir à jour à mesure que leur code change, souligne IBM.

OpenAPI Comment Parser est une bibliothèque est conçue pour Node.js, mais elle peut fonctionner avec n'importe quel langage qui utilise ce style de commentaires:

/**
* GET /users/{userId}
* @summary Returns a user by ID.
* @pathParam {int64} userId - The user's ID.
* @response 200 - OK
*/

OpenAPI Comment Parser est un logiciel libre sous licence Apache 2.0, disponivle sur GitHub.

[video:https://www.youtube.com/watch?v=-Z9Zn8RHf0c autoplay:0]

Stack Overflow lance Documentation

Soumis par fredericmazue le
Web

Stack Overflow lance Documentation, sa nouvelle section destinée aux développeurs. Jay Hanlon, chez Stack Overflow, explique la démarche : « Stack Overflow Documentation a pour ambition de résoudre les problèmes auxquels les développeurs sont confrontés au quotidien, et ce, en exploitant les ressources mises à disposition par notre immense communauté. »
 
Les exemples sont regroupés par tag et classés selon leur popularité en nombre de votes. Contrairement à la section Q&A de Stack Overflow, qui offre des réponses à des questions spécifiques, Documentation propose des solutions générales, applicables à de multiples cas similaires.

stackoverflow.com/documentation

Conférence Asciidoctor au LorraineJUG

Soumis par fredericmazue le

Le Lorraine JUG (Java User Group de Lorraine) organise une soirée de conférence en compagnie de Guillaume SCHEIBEL, développeur chez Expedia, pour découvrir Asciidoctor.

Au programme de la soirée :

18:15 - Accueil et enregistrement

18:30 - Asciidoctor avec Guillaume SCHEIBEL

“Est-ce que la doc est à jour ?”, “Elle est où la doc de la v1.5?”, “C’est quoi la différence avec la version précédente ?”, “C’est fatiguant de recréer à la main le PDF à chaque nouvelle version de l’application !”, “Comment je génère la table des matières dans cette m**!”, “Arf Word m’a encore pété mes listes numérotés !”

Ecrire de la documentation, c’est la plupart du temps dans un fichier complètement distinct de l’application dont le format est contraignant pour le développeur, ce qui entraîne sa frustration et le résultat s’en ressent sur le livrable final. S’occuper de la forme n’est pas notre activité de prédilection, nous c’est le fond. Tout cela pour que ce document soit déposé dans un répertoire partagé voir au mieux dans une GED. Ne parlons même pas du fait d’essayer de voir la différence entre deux versions!

Si cette introduction vous est familière alors Asciidoctor est là pour vous. Simple, clair et concis. Durant cette présentation nous allons voir ensemble la syntaxe, l’intégration dans une applications et dans son cycle de vie ainsi que la personnalisation du rendu. Et vous vous rendrez compte que faire de la documentation n'est pas forcément une prise de tête.

20:30 - Drink et tombola…

14 Avril 2015, 18h30
TELECOM Nancy
193 avenue Paul Muller, 54602 Villers-lès-Nancy

Inscription gratuite ! Nombre de places limitées

Calenco, une solution collaborative Open Source pour documents riches

Soumis par fredericmazue le

NeoDoc, société spécialisée dans la production, le stockage et la diffusion de la documentation technique, présente Calenco son serveur libre de travail collaboratif pour la création de documents enrichis.

Par sa conception, le système Calenco veut faciliter les projets documentaires complexes en permettant à tous les intervenants de la chaîne de production (rédacteurs, illustrateurs, relecteurs, traducteurs, etc.) de travailler sur des documents structurés destinés à plusieurs formats de publication (multisupport : PDF (Portable Document Format), HTML (HyperText Markup Language), etc.), et en centralisant leurs contributions.

Logiciel 100% libre, Calenco est basé sur les technologies XML (eXtensible Markup Language) et J2EE (Java Enterprise Edition).

Son interface ouverte lui permet d'envisager l'intégration dans « l'infostructure » d'une entreprise pour exploiter les données existantes et publier les documents produits sur les systèmes déjà utilisés (GED (Gestion Électronique des Documents), intranet, site Web, etc.).

Calenco sera aussi disponible en mode SaaS (Software as a Service).

Pour en savoir plus : http://www.calenco.com

Calenco, une solution collaborative Open Source pour documents riches

Soumis par fredericmazue le

NeoDoc, société spécialisée dans la production, le stockage et la diffusion de la documentation technique, présente Calenco son serveur libre de travail collaboratif pour la création de documents enrichis.

Par sa conception, le système Calenco veut faciliter les projets documentaires complexes en permettant à tous les intervenants de la chaîne de production (rédacteurs, illustrateurs, relecteurs, traducteurs, etc.) de travailler sur des documents structurés destinés à plusieurs formats de publication (multisupport : PDF (Portable Document Format), HTML (HyperText Markup Language), etc.), et en centralisant leurs contributions.

Logiciel 100% libre, Calenco est basé sur les technologies XML (eXtensible Markup Language) et J2EE (Java Enterprise Edition).

Son interface ouverte lui permet d'envisager l'intégration dans « l'infostructure » d'une entreprise pour exploiter les données existantes et publier les documents produits sur les systèmes déjà utilisés (GED (Gestion Électronique des Documents), intranet, site Web, etc.).

Calenco sera aussi disponible en mode SaaS (Software as a Service).

Pour en savoir plus : http://www.calenco.com