Making (Drupal) Documentation Modular, Reusable and Open Source how Darwin can help our angels   SFD Szeged 2011
Attending “Making Documentation Modular, Reusable and Open Source” by @kvantomme #szszk2011 #DITA
What to expect <ul><li>The source of all broken documentation
An intro to single sourcing
An intro to DITA
A future vision
2 shameless plugs
GOAL:
a  starting  point to lean startup methodologies </li></ul>
How do you do documentation? <ul><li>Do you have a product?
Do you deliver custom products (services)?
Are you happy with your documentation?
Are you using an open source platform? </li></ul>
Documentation of Open Source projects is broken
Why?
Developers only really document in code
Symptoms
We don't collaborate
We don't reuse
We don't adapt
Solution
Introduction to single sourcing <ul><li>Content assembly, including translation and localization
Different contexts of use
Technical publishing in different formats </li></ul>MINIMALISM, STRUCTURED
Introduction to DITA <ul><li>Darwin Information Typing Architecture (DITA)
Topic oriented  != book oriented
Maps:  Separation navigation & content
Conref:  content references = transclusion
Conditional text : context specific docs
Metadata : loads of it </li></ul>
DITA Information types <ul><li>3 core topic types: </li><ul><li>Task topic : how to
Concept topic :  e.g. definitions, rules, guidelines
Reference topic : e.g. API documentation </li></ul><li>Specialization: make your own topic type (Darwin...) </li></ul>
Combining Drupal & DITA
Future Vision for Drupal Docs <ul><li>Documentation becomes a modular patchable unit, that is used to build project docume...
Everyone contributes to documentation
A new niche grows in our community for technical writers
Projects can be documented from a Fingerprint (XML settings dump) </li></ul>
Upcoming SlideShare
Loading in …5
×

Dita documentation and open source sfd szeged 2011

1,080 views
1,044 views

Published on

Drupal is modular, reusable and open source, but that's not the case for it's documentation. The documentation in code falls under the GPL license and we have a few angels that contribute to our community documentation but on the documentation that we make for our users and customers we are failing to collaborate.

In this presentation I'll explain how we could turn documentation for open source projects into modular, reusable units on which we can collaborate. I'll explain what single sourcing is and how we could use it to make different types of documentation (e.g. manuals, help, training materials, training curricula, etc.) for different types of audiences from a single set of documents.

I'll give an introduction to DITA (Darwin Information Type Architecture), an Oasis XML standard started at IBM and how it's used in industries with modular products to publish documentation in a range of formats in minutes in stead of days while saving up to 60% of translation costs.

I'll also give a demonstration of the DITA Drupal module and explain how we want to make Drupal a platform for community authored DITA documentation that does not require knowledge about DITA from it's contributors.

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
1,080
On SlideShare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
0
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Dita documentation and open source sfd szeged 2011

  1. 1. Making (Drupal) Documentation Modular, Reusable and Open Source how Darwin can help our angels SFD Szeged 2011
  2. 2. Attending “Making Documentation Modular, Reusable and Open Source” by @kvantomme #szszk2011 #DITA
  3. 3. What to expect <ul><li>The source of all broken documentation
  4. 4. An intro to single sourcing
  5. 5. An intro to DITA
  6. 6. A future vision
  7. 7. 2 shameless plugs
  8. 8. GOAL:
  9. 9. a starting point to lean startup methodologies </li></ul>
  10. 10. How do you do documentation? <ul><li>Do you have a product?
  11. 11. Do you deliver custom products (services)?
  12. 12. Are you happy with your documentation?
  13. 13. Are you using an open source platform? </li></ul>
  14. 14. Documentation of Open Source projects is broken
  15. 15. Why?
  16. 16. Developers only really document in code
  17. 17. Symptoms
  18. 18. We don't collaborate
  19. 19. We don't reuse
  20. 20. We don't adapt
  21. 21. Solution
  22. 22. Introduction to single sourcing <ul><li>Content assembly, including translation and localization
  23. 23. Different contexts of use
  24. 24. Technical publishing in different formats </li></ul>MINIMALISM, STRUCTURED
  25. 25. Introduction to DITA <ul><li>Darwin Information Typing Architecture (DITA)
  26. 26. Topic oriented != book oriented
  27. 27. Maps: Separation navigation & content
  28. 28. Conref: content references = transclusion
  29. 29. Conditional text : context specific docs
  30. 30. Metadata : loads of it </li></ul>
  31. 31. DITA Information types <ul><li>3 core topic types: </li><ul><li>Task topic : how to
  32. 32. Concept topic : e.g. definitions, rules, guidelines
  33. 33. Reference topic : e.g. API documentation </li></ul><li>Specialization: make your own topic type (Darwin...) </li></ul>
  34. 34. Combining Drupal & DITA
  35. 35. Future Vision for Drupal Docs <ul><li>Documentation becomes a modular patchable unit, that is used to build project documentation
  36. 36. Everyone contributes to documentation
  37. 37. A new niche grows in our community for technical writers
  38. 38. Projects can be documented from a Fingerprint (XML settings dump) </li></ul>
  39. 39. What Drupal brings to DITA <ul><li>An open source option
  40. 40. Interoperability
  41. 41. Extensibility
  42. 42. Human friendly metadata handling
  43. 43. Game dynamics (user points)
  44. 44. social graph (Facebook integration)
  45. 45. Community tools (those web 2.0 things)
  46. 46. RDFa (those web 3.0 things) </li></ul>
  47. 47. What Drupal needs from DITA <ul><li>Best practices for single source documentation </li><ul><li>DITA maps
  48. 48. Conditional text
  49. 49. Conrefs
  50. 50. Topic based documentation </li></ul><li>Ecosystem of documentation tools & services
  51. 51. More documentation writers </li></ul>
  52. 52. Drupal DITA forms <ul><li>Use friendly flexible UI to create documentation forms
  53. 53. Store in Drupal, export in DITA
  54. 54. Currently implemented for tasks and concepts </li></ul>
  55. 55. Drupal DITA forms
  56. 56. Drupal DITA form builder (CCK)
  57. 57. Import existing documentation <ul><li>Upload individual files
  58. 58. Import folders </li><ul><li>Automatic checkout from a version controlled documentation repository
  59. 59. Drupal checks for updates </li></ul><li>Other import options can be tailored for specific use cases to plug into existing processes </li></ul>
  60. 60. Folder importer
  61. 61. User driven assembly and export <ul><li>Bookmark relevant documentation topics
  62. 62. Create a new DITA map in the GUI
  63. 63. Export the map and the topics it contains </li></ul>
  64. 64. Ditamaps as mindmaps
  65. 65. Add content with Views queries
  66. 66. Ditamaps as mindmaps
  67. 67. Export with Open Toolkit
  68. 68. You can download this for free at http://drupal.org/project/dita
  69. 69. Future Vision DITA in Drupal <ul><li>Metadata integration
  70. 70. DITA form to DITA XML Graphical UI
  71. 71. Authoring memory
  72. 72. Conref library
  73. 73. WYSIWYG or markup
  74. 74. 1 or more distributions: </li><ul><li>Documentation distribution
  75. 75. DITA distribution </li></ul></ul>
  76. 76. Are we there yet? <ul><li>Conditional text GsoC
  77. 77. Outlines as maps -> new hierarchy for book?
  78. 78. Help in core initiative </li></ul>
  79. 79. Imagine...
  80. 80. Documentation in a distro world
  81. 81. Shameless plug
  82. 82. http://topicforge.net/
  83. 83. [email_address]
  84. 84. Twitter @kvantomme LinkedIn be.linkedin.com/in/kvantomme [email_address]

×