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
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
55. Similarities with DITA
DITA Markdown
Separation of content and format ✓
Single source/Topic re-use ✓
Multichannel publishing ✓
Tools independent ✓
File based storage ✓
Maps ✓
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
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)
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
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>
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