documentation an engineering problem unsolved

Developer UG Dec 2015

DOCUMENTATION: AN

ENGINEERING PROBLEM

UNSOLVEDSchalk W. Cronjé

About meEmail:

Twitter / Ello : @ysb33r

Github:

ysb33r@gmail.com

https://github.com/ysb33r

Way back in 1997…

Information Mapping®Chunking - Information in small manageable units.

Consistency - Format, structure.

Integrated graphics - Diagrams & tables are part of thetext.

Accessible detail - Put what the reader needs, where thereader needs it.

http://www.informationmapping.com/en/

2004…

Agile Documentation, Andreas Rüpling

Knowledge Management ConceptsDocument Landscape

Wiki

Code-Doc Proximity

Code­Doc ProximityThe further the distance between the code and the

documentation, the lower the probability of the

documentation being maintained.

Desire #1We want to use the same editor for code & docs

so that we do not have to switch tools.

2005…

Wellsprings of Knowledge, Dorothy Leonard

Signature SkillsPeople will development affinities for certain tools

When the user has to fight the tool, the tool will not getused effectively (or not at all).

WYSIWIG

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

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

Tracking changesEngineering has already solved this problem.

Source control (Git, Subversion and others).

Easy to diff between changesets.

Collaborate with multiple commits and merging.

Desire #4We want to store document source in a textual,

non-proprietary format, so that we can use existing

tools and track the changes.

Desire #5We want to concurrently, collaborate on documents

and modify them without fear.

AutomationCI & CD and standard engineering practices.

Commit → Build → Feedback → Publish

Desire #5We want documentation to be built

and published automatically.

Desire #6We want our documentation to be

included with software publications.

We want…to use the same editor for code & docs so that we do nothave 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-proprietaryformat.

documentation to be built and published automatically.

documentation to be included with software publication.

2014… State of Simple Publising

Introducing Asciidoctorhttps://github.com/asciidoctor

http://asciidoctor.org

(Go explore yourself happy)

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.

FlavoursAsciidoctor (Ruby)

Asciidoctorj (JVM)

Asciidoctorjs (Javascript)

Original Asciidoc (Python)

2015… State of Asciidoctor

Drawing supportPlantUML

Ditaa

Shaape

BlockDiag, SeqDiag, ActDiag, NwDiag

GraphViz DOT

Via asciidoctor-diagram module

Drawing support +-------------+

| Asciidoctor |-------+

| diagram | |

+-------------+ | PNG out

^ |

| ditaa in |

| v

+--------+ +--------+----+ /---------------\

| |-->+ Asciidoctor +--->| |

| Text | +-------------+ | Beautiful |

|Document| | !magic! | | Output |

| {d}| | | | |

+---+----+ +-------------+ \---------------/

Drawing support

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;

}

Buildtool supportMaven

Gradle

Ant

Leiningen

SBT

Grunt

ProjectsA number of projects use Asciidoctor for documentation

complete with tested code snippets, including:

Groovy Language

Spring

Griffon

Actively in the worksAsciidoctor → Leanpub

Asciidoctor → Mallard

Asciidoctor → LaTeX

Asciidoctor → Pdf

Asciidoctor → Epub

About this presentationWritten in Asciidoctor (1.5.3.2)

Styled by asciidoctor-revealjs extension

Built using:

Gradle

gradle-asciidoctor-plugin

gradle-vfs-plugin

Demo

Books in Asciidoctor

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

Try it outInstall via Rubygems

Command-line asciidoctorj

Download OR

SDKman ( )

Docker

asciidoctor/docker-asciidoctor

Browser plugins

Build tools

http://sdkman.io

Thank youSchalk W. Cronjé

ysb33r@gmail.com

@ysb33r

Read more at http://asciidoctor.org