Upload
schalk-cronje
View
837
Download
3
Embed Size (px)
Citation preview
Developer UG Dec 2015
DOCUMENTATION: AN
ENGINEERING PROBLEM
UNSOLVEDSchalk W. Cronjé
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
CodeDoc 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