Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

2017-06-22 Documentation as code

0 views

Published on

Slide de ma présentation au Voxxed Days Luxembourg 2017.
http://cfp-voxxed-lux.yajug.org/2017/talk/KMC-5325/Documentation_as_code:_controler_la_qualite_!

"Document as code" consiste à utiliser toutes les bonnes pratiques que nous utilisons pour notre source code et de les appliquer à la documentation. Les points clés sont :

* Utiliser un outil de gestion des sources (git) et de préférence le même que pour les sources.
* Un format de texte simple (pas de XML) comme AsciiDoc.
* Mettre en place des outils d'intégration continu et déploiement continu

Lorsque cette bonne pratique est en place, se pose une seconde catégorie de problème. Comment garantir la qualité :

* Faciliter la barrière à l’entrée en proposant un lien pour éditer la documentation sur chaque page et pour soumettre une pull request.
* Test systématique des exemples de code
* Respect des conventions de documentation
* Métriques et dashboard pour garantir la qualité
* Partage de bonnes pratiques/revue de documentation.

Cette présentation est un retour d’expérience et donne quelques bonnes pratiques de documentation. C'est un aperçu de ce qui peut être mis en place pour s’assurer de la qualité de la doc.

Published in: Software
  • Be the first to comment

  • Be the first to like this

2017-06-22 Documentation as code

  1. 1. #DocAsCode #voxxed_lu Voxxed Days Luxembourg Jérémie Bresson – 22.06.2017 Documentation as code: contrôler la qualité !
  2. 2. #DocAsCode #voxxed_lu
  3. 3. #DocAsCode #voxxed_lu
  4. 4. #DocAsCode #voxxed_lu «Documentation as code»
  5. 5. #DocAsCode #voxxed_lu Qui suis je? Jérémie Bresson /@j2r2b /+JeremieBresson /jmini
  6. 6. #DocAsCode #voxxed_lu  BSI CRM  Eclipse Scout http://eclipse.org/scout/ Mon travail chez BSI
  7. 7. #DocAsCode #voxxed_lu «Documentation as code»
  8. 8. #DocAsCode #voxxed_lu «Documentation as code» en une image… java pom.xml docs #DocAsCode #voxxed_lu
  9. 9. #DocAsCode #voxxed_lu La syntaxe «AsciiDoc» = Getting Started with Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application prints _Hello World!_ to the console. * Compile this source to a class file using `javac`. * Run the compiled class file using `java`. If you need help with the Java syntax check the link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc].
  10. 10. #DocAsCode #voxxed_lu La syntaxe «AsciiDoc» = Getting Started with Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application prints _Hello World!_ to the console. * Compile this source to a class file using `javac`. * Run the compiled class file using `java`. If you need help with the Java syntax check the link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc]. Document Title Section Level 1
  11. 11. #DocAsCode #voxxed_lu La syntaxe «AsciiDoc» = Getting Started with Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application prints _Hello World!_ to the console. * Compile this source to a class file using `javac`. * Run the compiled class file using `java`. If you need help with the Java syntax check the link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc]. Unordered list items
  12. 12. #DocAsCode #voxxed_lu La syntaxe «AsciiDoc» = Getting Started with Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application prints _Hello World!_ to the console. * Compile this source to a class file using `javac`. * Run the compiled class file using `java`. If you need help with the Java syntax check the link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc]. bold italic code
  13. 13. #DocAsCode #voxxed_lu La syntaxe «AsciiDoc» = Getting Started with Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application prints _Hello World!_ to the console. * Compile this source to a class file using `javac`. * Run the compiled class file using `java`. If you need help with the Java syntax check the link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc]. External link with title
  14. 14. #DocAsCode #voxxed_lu La syntaxe «AsciiDoc» = Getting Started with Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application prints _Hello World!_ to the console. * Compile this source to a class file using `javac`. * Run the compiled class file using `java`. If you need help with the Java syntax check the link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc].
  15. 15. #DocAsCode #voxxed_lu La syntaxe «AsciiDoc» = Getting Started with Java Author Name <author@example.org> == Hello World example Copy the *HelloWorld.java* file. TIP: The application prints _Hello World!_ to the console. * Compile this source to a class file using `javac`. * Run the compiled class file using `java`. If you need help with the Java syntax check the link:http://docs.oracle.com/javase/8/docs/[Java 8 Javadoc].
  16. 16. #DocAsCode #voxxed_lu#DocAsCode #voxxed_lu
  17. 17. #DocAsCode #voxxed_lu Et la qualité?
  18. 18. #DocAsCode #voxxed_lu Dans «documentation as code» il y a «as code» !
  19. 19. #DocAsCode #voxxed_lu Faciliter les contributions
  20. 20. #DocAsCode #voxxed_lu Edit on GitHub
  21. 21. #DocAsCode #voxxed_lu#DocAsCode #voxxed_lu
  22. 22. #DocAsCode #voxxed_lu Contrôle continu des exemples de code
  23. 23. #DocAsCode #voxxed_lu [[lst-wikitext1, Listing 1]] [source,java] ---- public static String toHtml(String mediawikiText) { StringWriter writer = new StringWriter(); MarkupParser parser = new MarkupParser(new MediaWikiLanguage(), n parser.parse(mediawikiText); // <1> return writer.toString(); } ---- <1> Main call of the Mylyn Wikitext framework == Usage of Mylyn wikitext With the method `toHtml(String)` in <<lst-wikitext1>> you can convert a text from Mediawiki Language to HTML.
  24. 24. #DocAsCode #voxxed_lu [[lst-wikitext1, Listing 1]] [source,java] ---- public static String toHtml(String mediawikiText) { StringWriter writer = new StringWriter(); MarkupParser parser = new MarkupParser(new MediaWikiLanguage(), n parser.parse(mediawikiText); // <1> return writer.toString(); } ---- <1> Main call of the Mylyn Wikitext framework == Usage of Mylyn wikitext With the method `toHtml(String)` in <<lst-wikitext1>> you can convert a text from Mediawiki Language to HTML.
  25. 25. #DocAsCode #voxxed_lu [[lst-wikitext1, Listing 1]] [source,java] ---- public static String toHtml(String mediawikiText) { StringWriter writer = new StringWriter(); MarkupParser parser = new MarkupParser(new MediaWikiLanguage(), n parser.parse(mediawikiText); // <1> return writer.toString(); } ---- <1> Main call of the Mylyn Wikitext framework == Usage of Mylyn wikitext With the method `toHtml(String)` in <<lst-wikitext1>> you can convert a text from Mediawiki Language to HTML.
  26. 26. #DocAsCode #voxxed_lu
  27. 27. #DocAsCode #voxxed_lu
  28. 28. #DocAsCode #voxxed_lu [[lst-wikitext1, Listing 1]] [source,java] ---- public static String toHtml(String mediawikiText) { StringWriter writer = new StringWriter(); MarkupParser parser = new MarkupParser(new MediaWikiLanguage(), n parser.parse(mediawikiText); // <1> return writer.toString(); } ---- <1> Main call of the Mylyn Wikitext framework == Usage of Mylyn wikitext With the method `toHtml(String)` in <<lst-wikitext1>> you can convert a text from Mediawiki Language to HTML.
  29. 29. #DocAsCode #voxxed_lu [[lst-wikitext1, Listing 1]] [source,java] ---- include::src/main/java/MediawikiTest.java[tags=method] ---- <1> Main call of the Mylyn Wikitext framework == Usage of Mylyn wikitext With the method `toHtml(String)` in <<lst-wikitext1>> you can convert a text from Mediawiki Language to HTML. code snippet taken from real source code
  30. 30. #DocAsCode #voxxed_lu public class MediawikiTest { //tag::method[] public static String toHtml(String mediawikiText) { StringWriter writer = new StringWriter(); MarkupParser parser = new MarkupParser(new MediaWikiLanguage(), new H parser.parse(mediawikiText); // <1> return writer.toString(); } //end::method[] @Test public void test() { StringBuilder sb = new StringBuilder(); sb.append("= Heading 1 =n"); sb.append("n"); sb.append("Hello World!n"); sb.append("n"); #DocAsCode #voxxed_lu
  31. 31. #DocAsCode #voxxed_lu Surveiller l’évolution des sources
  32. 32. #DocAsCode #voxxed_lu * Add page `OrganizationTablePage` with title "Organizations" using the Scout new page wizard [[lst-contacts_OrganizationTablePage, Listing OrganizationTablePage]] [source,java] .Initial implementation of class OrganizationTablePage. ---- include::{codedir}/contacts/org.eclipse.scout.contacts.clie ---- <1> Make sure to add a translated text entry for "Organizations" using the Scout NLS tooling The implementation of class `OrganizationTablePage` using the Scout new page wizard then looks as shown in <<lst- contacts_OrganizationTablePage>>.
  33. 33. #DocAsCode #voxxed_lu
  34. 34. #DocAsCode #voxxed_lu // tag::PageInit[] // tag::childPage[] @PageData(OrganizationTablePageData.class) public class OrganizationTablePage extends AbstractPageWithTable<OrganizationTablePage.Table> { // end::childPage[] @Override protected String getConfiguredTitle() { return TEXTS.get("Organizations"); // <1> } // end::PageInit[] // tag::childPage[] @Override protected IPage<?> execCreateChildPage(ITableRow row) { OrganizationNodePage childPage;
  35. 35. #DocAsCode #voxxed_lu Build Logs 2017-06-12 15:51:21.337 [INFO] 2017-06-12 15:51:21.338 [INFO] --- asciidoctor-maven-plugin:1.5.5:process-asciidoc (boo 2017-06-12 15:51:24.852 [INFO] Using 'UTF-8' encoding to copy filtered resources. 2017-06-12 15:51:24.852 [INFO] ignoreDelta true 2017-06-12 15:51:24.856 [INFO] Copying 0 resource 2017-06-12 15:51:39.970 asciidoctor: WARNING: _TutorialStep2.adoc: line 247: no callout 2017-06-12 15:52:16.775 [INFO] 2017-06-12 15:52:16.775 [INFO] --- asciidoctor-maven-plugin:1.5.5:process-asciidoc (boo 2017-06-12 15:52:17.190 [INFO] Using 'UTF-8' encoding to copy filtered resources. 2017-06-12 15:52:17.191 [INFO] ignoreDelta true 2017-06-12 15:52:17.191 [INFO] Copying 0 resource
  36. 36. #DocAsCode #voxxed_lu Warning  Dans les logs => Monitorer https://github.com/asciidoctor/asciidoctor/issues/44
  37. 37. #DocAsCode #voxxed_lu Surveiller les documents produits
  38. 38. #DocAsCode #voxxed_lu  Organization: jmini  Repository: jxlint-experiments https://github.com/jmini/jxlint-experiments/  Organization: eclipsescout  Repository: eclipsescout.github.io https://github.com/eclipsescout/eclipsescout.github.io GitHub pages https://eclipsescout.github.io https://jmini.github.io/jxlint-experiments master gh-pages
  39. 39. #DocAsCode #voxxed_lu
  40. 40. #DocAsCode #voxxed_lu HTML output
  41. 41. #DocAsCode #voxxed_lu git commit -a -m "Update doc ${DOC_JOB_VERSION}" || true Execute shell git add -A && git commit -m "Update doc ${DOC_JOB_VERSION}" || true Jenkins config
  42. 42. #DocAsCode #voxxed_lu Le pipeline complet docs #DocAsCode #voxxed_lu
  43. 43. #DocAsCode #voxxed_lu <h2 id="scout-platform"><a class="anchor" href="#scout-platform" <div class="sectionbody"> <div class="paragraph"> <p>Scout contains a platform which provides basic functionali </div> <div class="ulist"> <ul> <li> <p><a href="#sec-app.lifecycle">Application Lifecycle M <li> <p><a href="#sec-bean.manager">Object Instance Manageme <li> <p><a href="#sec-config.management">Configuration Manag <li> <p><a href="#sec-class.inventory">Application Inventory <div class="sect1">
  44. 44. #DocAsCode #voxxed_lu Contrôle manuel
  45. 45. #DocAsCode #voxxed_lu
  46. 46. #DocAsCode #voxxed_lu
  47. 47. #DocAsCode #voxxed_lu
  48. 48. #DocAsCode #voxxed_lu
  49. 49. #DocAsCode #voxxed_lu  Screenshots würde ich jeweils ohne den Browserrahmen machen  Die Bildbeschriftungen sind noch auf Englisch (Figure statt Abbildung)
  50. 50. #DocAsCode #voxxed_lu
  51. 51. #DocAsCode #voxxed_lu «documentation as code» «automatisation»
  52. 52. #DocAsCode #voxxed_lu Merci /@j2r2b /+JeremieBresson /jmini jeremie.bresson@bsi-software.com

×