Ce diaporama a bien été signalé.
Nous utilisons votre profil LinkedIn et vos données d’activité pour vous proposer des publicités personnalisées et pertinentes. Vous pouvez changer vos préférences de publicités à tout moment.
Markdown
Friend or
Foe?
Ellis Pratt
@ellispratt
About me
Director at Cherryleaf,
a technical writing services and training
company in the UK
About you
Who uses DITA, S1000D or similar?
About you
How much have you spent on software, training
and consultancy?
Overview
1. Some home truths
2. What is Markdown?
3. What can it do?
4. Managing your content
5. How does it compare to DI...
1.Some home truths
DITA is 11 years old
After 11 years
≃9%
of Technical Authors
are using
DITA
23 April 2016
After 11 years
≃4%
of technical writing
job adverts
mention
DITA
23 April 2016
DITA has not taken
over the world
and
Technical Authors’ tools are
seen as
Difficult to use
Hard to write
Hard to read
Technical Authors’ tools are
Complex tools for
complex problems
Not particularly
cheap
Only used by
Technical Authors
and
Developers now see XML as
Verbose
Old-fashioned
<?xml version="1.0" encoding="utf-8"?>
<Patient xmlns="http://hl7.org/fhir...
and
Help has moved partly to
So
People have been
looking at alternative
solutions
2.What is Markdown?
Markdown
Simple tool for simple
problems
Created as a faster
way to create HTML
A lightweight syntax
used for generating
H...
Demo of Markdown
authoring tool
If that looks familiar
Many web apps use
Markdown
(early versions)
Flavours of Markdown
People have added
extra functionality to
the original standard
Markdown-like alternatives
AsciiDoc
reStructuredTex
(reST)
Markdown authoring tools
Less sophisticated
Built to suit the
developers’ workflow
Low cost, open
source
Simple markup
3.What can it do?
Demo of Markdown
publishing tool
Single source content
Multi-channel publishing
Variables
Templates
The closest you get
to strict information
typing
Uses a scripting
language (liquid) with
Markdown
Conditional text (sort of)
Add review comments and
track changes
Link validation
(but link management can be problematic)
Colour coded syntax
4.Managing your
content
It’s usually a file-based topic
model
Documentation can be treated like code
Source control/Binding
Versioning
“Flat file” CMS
Demo of flat file CMS
Automatic builds
Stenodict example
https://github.com/openstenoproject/stenodict/blob/gh-pages/_dictionaries/
pokemon.md
becomes
http://www...
Continuous integration
e.g. Continuous
delivery with Jenkins,
Asciidoctor and
Gradle
Screenshots update with every new app...
Database driven local CMS
Cloud CMS
Collaborative writing
Shared
through
Google Drive
and Dropbox
Collaborative writing demo
Collaborative writing demo
Demo of CMS with templates
What happens when someone falls under a bus?
But Markdown document production
systems are often bespoke
5.How does it
compare to DITA?
Similarities with DITA
DITA Markdown
Separation of content and format ✓
Single source/Topic re-use ✓
Multichannel publishi...
Extensions
DITA Markdown
Keyref/variables
😀
Conditional publishing
😮
Metadata
😀
L18N attribute
😟
Versioning
😮
Tables
😕
Xre...
Omissions
DITA Markdown
Strict information typing
(consistency) 😟
Transclusion 😟
Standards based 😟
Structured authoring 😟
...
Advantages over DITA
DITA Markdown
✘ Continuous deployment
✘
Add review comments and track
changes
✘ Coloured syntax for c...
6.When should you
use Markdown?
Where docs are a
team responsibility
Devs and Writers are one
team
Docs are be part of the
definition of Done
Docs are part...
If you need to make it easy
for developers to write
You need to fit into
the developers
workflow
Enabling them to use
their ...
If you have non-professional
writers contributing content
e.g. Sales proposals
The client wants to
edit the content
(custo...
If you are on tight budget
Or you can’t get 3rd
parties to spend
money on using your
authoring tools
If you have little time
Continuously
changing
applications
API documentation
Custom-deployed
software (for each
client)
7. When shouldn’t you
use it?
When shouldn’t you?
1. Your work requires a
standard
2. You need to extend the
markup with your own
syntax
3. You need sem...
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 si...
8. Interoperability
Hopefully we’ll see more
work on
Exporting to
Markdown
Round-tripping
Markdown
Image: Roger Sheen
DITA-OT Markdown plugin
You can use
Markdown files
directly in DITA topic
references
You can also publish
DITA content to t...
DITA Glass
Lightweight DITA
It promises
DITA<-->Markdown
format mappings
So you could use both
Use DITA for complex
content
Use Markdown for
simple content
Content APIs
All the created content
is accessible via an
API
Bring your content
anywhere, display it
as you like
Contentf...
And there’s AsciiDoc
Supports DocBook
Can be set up to
work with Jekyll and
other tools
Summary
What are the takeaways?
It’s simple,
lightweight and low
cost
It can do a lot
Developers love it
Questions
For more information
ellis@cherryleaf.com
@ellispratt
End
© Cherryleaf 2016
Images and
screenshots © their
respective owners
Prochain SlideShare
Chargement dans…5
×

Markdown - friend or foe?

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

  • Soyez le premier à commenter

Markdown - friend or foe?

  1. 1. Markdown Friend or Foe? Ellis Pratt @ellispratt
  2. 2. About me Director at Cherryleaf, a technical writing services and training company in the UK
  3. 3. About you Who uses DITA, S1000D or similar?
  4. 4. About you How much have you spent on software, training and consultancy?
  5. 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. 6. 1.Some home truths
  7. 7. DITA is 11 years old
  8. 8. After 11 years ≃9% of Technical Authors are using DITA 23 April 2016
  9. 9. After 11 years ≃4% of technical writing job adverts mention DITA 23 April 2016
  10. 10. DITA has not taken over the world
  11. 11. and
  12. 12. Technical Authors’ tools are seen as Difficult to use Hard to write Hard to read
  13. 13. Technical Authors’ tools are Complex tools for complex problems Not particularly cheap Only used by Technical Authors
  14. 14. and
  15. 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. 16. and
  17. 17. Help has moved partly to
  18. 18. So
  19. 19. People have been looking at alternative solutions
  20. 20. 2.What is Markdown?
  21. 21. Markdown Simple tool for simple problems Created as a faster way to create HTML A lightweight syntax used for generating HTML
  22. 22. Demo of Markdown authoring tool
  23. 23. If that looks familiar
  24. 24. Many web apps use Markdown (early versions)
  25. 25. Flavours of Markdown People have added extra functionality to the original standard
  26. 26. Markdown-like alternatives AsciiDoc reStructuredTex (reST)
  27. 27. Markdown authoring tools Less sophisticated Built to suit the developers’ workflow Low cost, open source Simple markup
  28. 28. 3.What can it do?
  29. 29. Demo of Markdown publishing tool
  30. 30. Single source content
  31. 31. Multi-channel publishing
  32. 32. Variables
  33. 33. Templates The closest you get to strict information typing Uses a scripting language (liquid) with Markdown
  34. 34. Conditional text (sort of)
  35. 35. Add review comments and track changes
  36. 36. Link validation (but link management can be problematic)
  37. 37. Colour coded syntax
  38. 38. 4.Managing your content
  39. 39. It’s usually a file-based topic model Documentation can be treated like code
  40. 40. Source control/Binding
  41. 41. Versioning
  42. 42. “Flat file” CMS
  43. 43. Demo of flat file CMS
  44. 44. Automatic builds
  45. 45. Stenodict example https://github.com/openstenoproject/stenodict/blob/gh-pages/_dictionaries/ pokemon.md becomes http://www.openstenoproject.org/stenodict/dictionaries/pokemon.html
  46. 46. Continuous integration e.g. Continuous delivery with Jenkins, Asciidoctor and Gradle Screenshots update with every new application build
  47. 47. Database driven local CMS
  48. 48. Cloud CMS
  49. 49. Collaborative writing Shared through Google Drive and Dropbox
  50. 50. Collaborative writing demo
  51. 51. Collaborative writing demo
  52. 52. Demo of CMS with templates
  53. 53. What happens when someone falls under a bus? But Markdown document production systems are often bespoke
  54. 54. 5.How does it compare to DITA?
  55. 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. 56. Extensions DITA Markdown Keyref/variables 😀 Conditional publishing 😮 Metadata 😀 L18N attribute 😟 Versioning 😮 Tables 😕 Xrefs 😕 Glossaries and Indexes 😕
  57. 57. Omissions DITA Markdown Strict information typing (consistency) 😟 Transclusion 😟 Standards based 😟 Structured authoring 😟 Extensible (shareable) 😟 Dynamic heading level rendering 😟
  58. 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. 59. 6.When should you use Markdown?
  60. 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. 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. 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. 63. If you are on tight budget Or you can’t get 3rd parties to spend money on using your authoring tools
  64. 64. If you have little time Continuously changing applications API documentation Custom-deployed software (for each client)
  65. 65. 7. When shouldn’t you use it?
  66. 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. 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. 68. 8. Interoperability
  69. 69. Hopefully we’ll see more work on Exporting to Markdown Round-tripping Markdown Image: Roger Sheen
  70. 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. 71. DITA Glass
  72. 72. Lightweight DITA It promises DITA<-->Markdown format mappings
  73. 73. So you could use both Use DITA for complex content Use Markdown for simple content
  74. 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. 75. And there’s AsciiDoc Supports DocBook Can be set up to work with Jekyll and other tools
  76. 76. Summary
  77. 77. What are the takeaways? It’s simple, lightweight and low cost It can do a lot Developers love it
  78. 78. Questions
  79. 79. For more information ellis@cherryleaf.com @ellispratt
  80. 80. End © Cherryleaf 2016 Images and screenshots © their respective owners

×