Cherryleaf’s Ellis Pratt will be speaking at Lavacon’s first European conference. This will be held on 5-8 June, at the Trinity College Conference Centre, Dublin. Ellis’ presentation will be on the 7th June 2016

1. Markdown
Friend or
Foe?
Ellis Pratt
@ellispratt

2. About me
Director at Cherryleaf,
a technical writing services and training
company in the UK

3. About you
Who uses DITA, S1000D or similar?

4. About you
How much have you spent on software, training
and consultancy?

5. Overview
1. Some home truths
2. What is Markdown?
3. What can it do?
4. Managing your content
5. How does it compare to DITA?
6. When should you use Markdown?
7. When shouldn’t you?
8. Interoperability
Image: Tim Peake

6. 1.Some home truths

7. DITA is 11 years old

8. After 11 years
≃9%
of Technical Authors
are using
DITA
23 April 2016

9. After 11 years
≃4%
of technical writing
job adverts
mention
DITA
23 April 2016

10. DITA has not taken
over the world

11. and

12. Technical Authors’ tools are
seen as
Difficult to use
Hard to write
Hard to read

13. Technical Authors’ tools are
Complex tools for
complex problems
Not particularly
cheap
Only used by
Technical Authors

14. and

15. Developers now see XML as
Verbose
Old-fashioned
<?xml version="1.0" encoding="utf-8"?>
<Patient xmlns="http://hl7.org/fhir">
<text>
<status value="generated" />
<div xmlns="http://www.w3.org/1999/xhtml">
<p>Harley N Hobbs</p>
<p>16 Pier Road</p>
<p>STANWARDINE IN THE FIELDS</p>
<p>SY4 7IW</p>
<p>Date of birth: 1966-06-07</p>
</div>
</text>
<identifier>
<use value="official" />
<type>
<coding>
<code value="SSN" />
</coding>
</type>
<system value="http://hl7.org/fhir/sid/us-ssn" />
<value value="1" />
</identifier>
<postalCode value="SY4 7IW" />
</address>
<careProvider>
<reference value="Organization/1" />
</careProvider>
</Patient>

16. and

17. Help has moved partly to

18. So

19. People have been
looking at alternative
solutions

20. 2.What is Markdown?

21. Markdown
Simple tool for simple
problems
Created as a faster
way to create HTML
A lightweight syntax
used for generating
HTML

22. Demo of Markdown
authoring tool

23. If that looks familiar

24. Many web apps use
Markdown
(early versions)

25. Flavours of Markdown
People have added
extra functionality to
the original standard

26. Markdown-like alternatives
AsciiDoc
reStructuredTex
(reST)

27. Markdown authoring tools
Less sophisticated
Built to suit the
developers’ workflow
Low cost, open
source
Simple markup

28. 3.What can it do?

29. Demo of Markdown
publishing tool

30. Single source content

31. Multi-channel publishing

32. Variables

33. Templates
The closest you get
to strict information
typing
Uses a scripting
language (liquid) with
Markdown

34. Conditional text (sort of)

35. Add review comments and
track changes

36. Link validation
(but link management can be problematic)

37. Colour coded syntax

38. 4.Managing your
content

39. It’s usually a file-based topic
model
Documentation can be treated like code

40. Source control/Binding

41. Versioning

42. “Flat file” CMS

43. Demo of flat file CMS

44. Automatic builds

45. Stenodict example
https://github.com/openstenoproject/stenodict/blob/gh-pages/_dictionaries/
pokemon.md
becomes
http://www.openstenoproject.org/stenodict/dictionaries/pokemon.html

46. Continuous integration
e.g. Continuous
delivery with Jenkins,
Asciidoctor and
Gradle
Screenshots update with every new application build

47. Database driven local CMS

48. Cloud CMS

49. Collaborative writing
Shared
through
Google Drive
and Dropbox

50. Collaborative writing demo

51. Collaborative writing demo

52. Demo of CMS with templates

53. What happens when someone falls under a bus?
But Markdown document production
systems are often bespoke

54. 5.How does it
compare to DITA?

55. Similarities with DITA
DITA Markdown
Separation of content and format ✓
Single source/Topic re-use ✓
Multichannel publishing ✓
Tools independent ✓
File based storage ✓
Maps ✓

56. Extensions
DITA Markdown
Keyref/variables
😀
Conditional publishing
😮
Metadata
😀
L18N attribute
😟
Versioning
😮
Tables
😕
Xrefs
😕
Glossaries and Indexes
😕

57. Omissions
DITA Markdown
Strict information typing
(consistency) 😟
Transclusion 😟
Standards based 😟
Structured authoring 😟
Extensible (shareable) 😟
Dynamic heading level rendering 😟

58. Advantages over DITA
DITA Markdown
✘ Continuous deployment
✘
Add review comments and track
changes
✘ Coloured syntax for code samples
✘ Put JavaScript tags directly in a topic
✘ Easy to read the markup
✘ Cost
✘ Speed of deployment

59. 6.When should you
use Markdown?

60. Where docs are a
team responsibility
Devs and Writers are one
team
Docs are be part of the
definition of Done
Docs are part of the
review process
Image: St Helens RFC

61. If you need to make it easy
for developers to write
You need to fit into
the developers
workflow
Enabling them to use
their own tools

62. If you have non-professional
writers contributing content
e.g. Sales proposals
The client wants to
edit the content
(custom
deployments)
You hate wrangling
Word files

63. If you are on tight budget
Or you can’t get 3rd
parties to spend
money on using your
authoring tools

64. If you have little time
Continuously
changing
applications
API documentation
Custom-deployed
software (for each
client)

65. 7. When shouldn’t you
use it?

66. When shouldn’t you?
1. Your work requires a
standard
2. You need to extend the
markup with your own
syntax
3. You need semantic
markup
4. You have non-trivial
L18N needs

67. When shouldn’t you?
5. You want DTP
6. You have complex
lists
7. Google’s custom
search engine isn’t
good enough
8. The simplicity is lost
due to customisation

68. 8. Interoperability

69. Hopefully we’ll see more
work on
Exporting to
Markdown
Round-tripping
Markdown
Image: Roger Sheen

70. DITA-OT Markdown plugin
You can use
Markdown files
directly in DITA topic
references
You can also publish
DITA content to the
Markdown format
<map>
<topicref
href="topic.md"
format="markdown"/>
</map>

71. DITA Glass

72. Lightweight DITA
It promises
DITA<-->Markdown
format mappings

73. So you could use both
Use DITA for complex
content
Use Markdown for
simple content

74. Content APIs
All the created content
is accessible via an
API
Bring your content
anywhere, display it
as you like
Contentful
Netflix API Image: Cleve Gibbon

75. And there’s AsciiDoc
Supports DocBook
Can be set up to
work with Jekyll and
other tools

76. Summary

77. What are the takeaways?
It’s simple,
lightweight and low
cost
It can do a lot
Developers love it

78. Questions

79. For more information
ellis@cherryleaf.com
@ellispratt

80. End
© Cherryleaf 2016
Images and
screenshots © their
respective owners