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.

1. #DocAsCode #voxxed_lu
Voxxed Days Luxembourg
Jérémie Bresson – 22.06.2017
Documentation as code:
contrôler la qualité !

2. #DocAsCode #voxxed_lu

3. #DocAsCode #voxxed_lu

4. #DocAsCode #voxxed_lu
«Documentation as code»

5. #DocAsCode #voxxed_lu
Qui suis je?
Jérémie Bresson
/@j2r2b
/+JeremieBresson
/jmini

6. #DocAsCode #voxxed_lu
 BSI CRM  Eclipse Scout
http://eclipse.org/scout/
Mon travail chez BSI

7. #DocAsCode #voxxed_lu
«Documentation as code»

8. #DocAsCode #voxxed_lu
«Documentation as code» en une image…
java
pom.xml
docs
#DocAsCode #voxxed_lu

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. #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. #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. #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. #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. #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. #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. #DocAsCode #voxxed_lu#DocAsCode #voxxed_lu

17. #DocAsCode #voxxed_lu
Et la qualité?

18. #DocAsCode #voxxed_lu
Dans «documentation as code»
il y a «as code» !

19. #DocAsCode #voxxed_lu
Faciliter les contributions

20. #DocAsCode #voxxed_lu
Edit on GitHub

21. #DocAsCode #voxxed_lu#DocAsCode #voxxed_lu

22. #DocAsCode #voxxed_lu
Contrôle continu des exemples de code

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. #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. #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. #DocAsCode #voxxed_lu

27. #DocAsCode #voxxed_lu

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. #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. #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. #DocAsCode #voxxed_lu
Surveiller l’évolution des sources

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. #DocAsCode #voxxed_lu

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. #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. #DocAsCode #voxxed_lu
Warning
 Dans les logs
=> Monitorer
https://github.com/asciidoctor/asciidoctor/issues/44

37. #DocAsCode #voxxed_lu
Surveiller les documents produits

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. #DocAsCode #voxxed_lu

40. #DocAsCode #voxxed_lu
HTML output

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. #DocAsCode #voxxed_lu
Le pipeline complet
docs
#DocAsCode #voxxed_lu

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. #DocAsCode #voxxed_lu
Contrôle manuel

45. #DocAsCode #voxxed_lu

46. #DocAsCode #voxxed_lu

47. #DocAsCode #voxxed_lu

48. #DocAsCode #voxxed_lu

49. #DocAsCode #voxxed_lu
 Screenshots würde ich jeweils ohne den
Browserrahmen machen
 Die Bildbeschriftungen sind noch auf Englisch
(Figure statt Abbildung)

50. #DocAsCode #voxxed_lu

51. #DocAsCode #voxxed_lu
«documentation as code»
«automatisation»

52. #DocAsCode #voxxed_lu
Merci
/@j2r2b
/+JeremieBresson
/jmini
jeremie.bresson@bsi-software.com