Following on from an idea of Dan Allan, this explores desires for authoring documentation from an engineering point of view. THhe second half looks at how Asciidoctor project is trying to address some of these desoires.

1. Developer UG Dec 2015
DOCUMENTATION: AN
ENGINEERING PROBLEM
UNSOLVED
Schalk W. Cronjé

2. About me
Email:
Twitter / Ello : @ysb33r
Github:
ysb33r@gmail.com
https://github.com/ysb33r

3. Way back in 1997…​

4. Information Mapping®
Chunking - Information in small manageable units.
Consistency - Format, structure.
Integrated graphics - Diagrams & tables are part of the
text.
Accessible detail - Put what the reader needs, where the
reader needs it.
http://www.informationmapping.com/en/

5. 2004…​
Agile Documentation, Andreas Rüpling

6. Knowledge Management Concepts
Document Landscape
Wiki
Code-Doc Proximity

7. Code­Doc Proximity
The further the distance between the code and the
documentation, the lower the probability of the
documentation being maintained.

8. Desire #1
We want to use the same editor for code & docs
so that we do not have to switch tools.

9. 2005…​
Wellsprings of Knowledge, Dorothy Leonard

10. Signature Skills
People will development affinities for certain tools
When the user has to fight the tool, the tool will not get
used effectively (or not at all).

11. WYSIWIG

12. Desire #2
We want to focus on content, not layout.

13. Desire #3
We want to use one source to publish to multiple formats.

14. Tracking changes
Engineering has already solved this problem.
Source control (Git, Subversion and others).
Easy to diff between changesets.
Collaborate with multiple commits and merging.

15. Desire #4
We want to store document source in a textual,
non-proprietary format, so that we can use existing
tools and track the changes.

16. Desire #5
We want to concurrently, collaborate on documents
and modify them without fear.

17. Automation
CI & CD and standard engineering practices.
Commit → Build → Feedback → Publish

18. Desire #5
We want documentation to be built
and published automatically.

19. Desire #6
We want our documentation to be
included with software publications.

20. We want…​
to use the same editor for code & docs so that we do not
have to switch tools.
to focus on content, not layout.
to use one source to publish to multiple formats.
to store document source in a textual, non-proprietary
format.
documentation to be built and published automatically.
documentation to be included with software publication.

21. 2014…​State of Simple Publising

22. Introducing Asciidoctor
https://github.com/asciidoctor
http://asciidoctor.org
(Go explore yourself happy)

23. Why?
Focus on content, not formatting.
Source-control friendly.
No proprietary source format.
More powerful than Markdown, including
Github MD.
Leanpub MD & Markuva.
More user friendly than RText or LaTeX.
No need to fight Docbook.

24. Flavours
Asciidoctor (Ruby)
Asciidoctorj (JVM)
Asciidoctorjs (Javascript)
Original Asciidoc (Python)

25. 2015…​State of Asciidoctor

26. Drawing support
PlantUML
Ditaa
Shaape
BlockDiag, SeqDiag, ActDiag, NwDiag
GraphViz DOT
Via asciidoctor-diagram module

27. Drawing support
+-------------+
| Asciidoctor |-------+
| diagram | |
+-------------+ | PNG out
^ |
| ditaa in |
| v
+--------+ +--------+----+ /---------------
| |-->+ Asciidoctor +--->| |
| Text | +-------------+ | Beautiful |
|Document| | !magic! | | Output |
| {d}| | | | |
+---+----+ +-------------+ ---------------/

28. Drawing support

29. Source Code Highlighting
[source,cpp]
----
int main(int argc,char** argv) {
std::cout << "Hello, world!" << std::endl;
}
----
int main(int argc,char** argv) {
std::cout << "Hello, world!" << std::endl;
}

30. Buildtool support
Maven
Gradle
Ant
Leiningen
SBT
Grunt

31. Projects
A number of projects use Asciidoctor for documentation
complete with tested code snippets, including:
Groovy Language
Spring
Griffon

32. Actively in the works
Asciidoctor → Leanpub
Asciidoctor → Mallard
Asciidoctor → LaTeX
Asciidoctor → Pdf
Asciidoctor → Epub

33. About this presentation
Written in Asciidoctor (1.5.3.2)
Styled by asciidoctor-revealjs extension
Built using:
Gradle
gradle-asciidoctor-plugin
gradle-vfs-plugin

34. Demo

35. Books in Asciidoctor
Built by AsciidoctorJ + Leanpub backend (1.6.0-SNAPSHOT)
http://bit.ly/1iJmdiP

36. Try it out
Install via Rubygems
Command-line asciidoctorj
Download OR
SDKman ( )
Docker
asciidoctor/docker-asciidoctor
Browser plugins
Build tools
http://sdkman.io

37. Thank you
Schalk W. Cronjé
ysb33r@gmail.com
@ysb33r
Read more at http://asciidoctor.org