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.

Documentation An Engineering Problem Unsolved

982 views

Published on

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.

Published in: Software
  • Be the first to comment

Documentation An Engineering Problem Unsolved

  1. 1. Developer UG Dec 2015 DOCUMENTATION: AN ENGINEERING PROBLEM UNSOLVED Schalk W. Cronjé
  2. 2. About me Email: Twitter / Ello : @ysb33r Github: ysb33r@gmail.com https://github.com/ysb33r
  3. 3. Way back in 1997…​
  4. 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. 5. 2004…​ Agile Documentation, Andreas Rüpling
  6. 6. Knowledge Management Concepts Document Landscape Wiki Code-Doc Proximity
  7. 7. Code­Doc Proximity The further the distance between the code and the documentation, the lower the probability of the documentation being maintained.
  8. 8. Desire #1 We want to use the same editor for code & docs so that we do not have to switch tools.
  9. 9. 2005…​ Wellsprings of Knowledge, Dorothy Leonard
  10. 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. 11. WYSIWIG
  12. 12. Desire #2 We want to focus on content, not layout.
  13. 13. Desire #3 We want to use one source to publish to multiple formats.
  14. 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. 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. 16. Desire #5 We want to concurrently, collaborate on documents and modify them without fear.
  17. 17. Automation CI & CD and standard engineering practices. Commit → Build → Feedback → Publish
  18. 18. Desire #5 We want documentation to be built and published automatically.
  19. 19. Desire #6 We want our documentation to be included with software publications.
  20. 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. 21. 2014…​State of Simple Publising
  22. 22. Introducing Asciidoctor https://github.com/asciidoctor http://asciidoctor.org (Go explore yourself happy)
  23. 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. 24. Flavours Asciidoctor (Ruby) Asciidoctorj (JVM) Asciidoctorjs (Javascript) Original Asciidoc (Python)
  25. 25. 2015…​State of Asciidoctor
  26. 26. Drawing support PlantUML Ditaa Shaape BlockDiag, SeqDiag, ActDiag, NwDiag GraphViz DOT Via asciidoctor-diagram module
  27. 27. Drawing support +-------------+ | Asciidoctor |-------+ | diagram | | +-------------+ | PNG out ^ | | ditaa in | | v +--------+ +--------+----+ /--------------- | |-->+ Asciidoctor +--->| | | Text | +-------------+ | Beautiful | |Document| | !magic! | | Output | | {d}| | | | | +---+----+ +-------------+ ---------------/
  28. 28. Drawing support
  29. 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. 30. Buildtool support Maven Gradle Ant Leiningen SBT Grunt
  31. 31. Projects A number of projects use Asciidoctor for documentation complete with tested code snippets, including: Groovy Language Spring Griffon
  32. 32. Actively in the works Asciidoctor → Leanpub Asciidoctor → Mallard Asciidoctor → LaTeX Asciidoctor → Pdf Asciidoctor → Epub
  33. 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. 34. Demo
  35. 35. Books in Asciidoctor Built by AsciidoctorJ + Leanpub backend (1.6.0-SNAPSHOT) http://bit.ly/1iJmdiP
  36. 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. 37. Thank you Schalk W. Cronjé ysb33r@gmail.com @ysb33r Read more at http://asciidoctor.org

×