George Bina: DITA for Developers and GitHub for Technical Writers

George Bina
george@oxygenxml.com
@georgebina #LavaCon
DITA for developers and
GitHub for technical writers

@georgebina #LavaCon Copyright @ Syncro Soft, 2016. All rights reserved.
DITA for developers and GitHub for technical writers
Using DITA and GitHub for both
technical writers and developers

Can we all work together?
GitHub
DITA
Developers
Technical Writers

What do we need?
GitHub
DITA
Developers
Technical Writers
Make DITA accessible to developers
Hide GitHub complexity from technical authors

Make DITA accessible
Lightweight or constrained DITA
•  Markdown
•  XML
Controlled authoring experience
•  placeholders
•  hints
•  inline actions and form controls
•  rules with automatic fixes
Recognize and convert to DITA different Markdown structures
Markdown à Lightweight DITA à DITA

Use Markdown to encode DITA topics
Support Markdown directly in DITA:
<topicref href=“topic.md" format="markdown"/>

Direct Markdown support
Authoring
•  Syntax highlighting
•  Helper actions to insert lists, tables, inlines
•  DITA preview (along with HTML preview)
Validation
•  Detect missing title, duplicate sections
Publishing
•  As if the DITA converted topic was referred

DITA-aware Markdown editor

Path from Markdown to DITA
•  Recognize Markdown fragments in DITA topics
•  Convert them automatically to DITA markup
Example:
* item 1
* item 2
* item 3
https://github.com/oxygenxml/ditaMark
•  item 1
•  item 2
•  item 3
<ul>
<li>item 1</li>
<li>item 2</li>
<li>item 3</li>
</ul>

Recognized Markdown patterns
•  Lists
* item or - item
•  Quotes
> text
•  Code blocks and inline code
``` code and `inline code`
•  Links
[link text](link URL) or <URL>
•  Images
![alternate text](URL) or ![alternate text](URL “title”)
•  Tables
|-|-|-|-| with or without a header
•  Titles
# title or ## section

Markdown lists to DITA

Controlled authoring experience
We can provide customized:
•  placeholders
•  hints
•  inline actions
•  inline form controls
Lightweight DITA example of controlled authoring
experience

Lightweight DITA topic

placeholder

hint
placeholder

hint
placeholder
inline actions

hint
placeholder
inline actions
inline form
controls

Hide GitHub complexity
From
•  Fork remote
•  Clone locally
•  Branch
•  Checkout working copy
•  Change
•  Commit locally
•  Push to remote
•  Send pull request
To
•  Change
•  Save/Commit
Automate parts of the contribution workflow

GitHub contribution workflow
original
remote
repository
your
remote
repository
1. fork
your local
repository
branch
2. clone
Working
copy
3. checkout
4. change
5. commit
6. push
7. pull
request
Edited
File
GitHub
Local

Simplified workflow
original
remote
repository
Edited
File
1. change
2. save/commit à push or fork + push + pull request

Integration is key to adoption
Interconnected services to achieve specific goals!
Services we will use in the following samples:
•  GitHub – storage, versions, user management,
web publishing
•  Jira – issue tracking, user management
•  Travis – continuous integration server
•  oXygen XML Web Author – XML authoring
•  Slack – project chat

Review documentation
Jira
Issue
•  description
•  comment
•  code changes
•  documentation
changes
Source repository
GitHub
•  Documentation
repository

Jira
Issue
•  description
•  comment
•  code changes
changes
Source repository
GitHub
repository
review/edit
modified
documentation

Jira
Issue
•  description
•  comment
•  code changes
changes
•  review/edit modified
documentation
Source repository
GitHub
repository
oXygen XML
Web Author

Email notifications with links

Link to changes topics
click to
review/edit

Immediate edit access

Click to see changes

Enable contributions from anyone
Website
Documentation
•  read
•  stars/comments
•  instructions on how
to access the
documentation
repository
GitHub
repository

Website
Documentation
•  read
•  link to edit current
documentation topic
GitHub
repository
oXygen XML
Web Author

Website
Documentation
•  read
•  link to edit current
documentation topic
GitHub
repository
oXygen XML
Web Author
Slack

oXygen User Guide
edit link
https://oxygenxml.com/doc/versions/18.0/ug-editor/topics/getting-started-intro.html

Immediate access to edit

Slack notifications on changes

DITA-OT documentation
edit link
http://www.dita-ot.org/dev/

Edit source

DITA+Markdown based Wiki
Website
(GitHub Pages)
link to edit page
GitHub
repository
oXygen XML
Web Author
Travis

Website content
https://georgebina.github.io/ghd-wiki/

History and Edit links

Revisions history

Controlled AX online editor

Markdown topic

GitHub Markdown editor

Travis project status
https://travis-ci.org/georgebina/ghd-wiki/builds

Take-aways
There is nothing that stops us from using DITA
with GitHub to provide similar systems as
Markdown+GitHub based systems
We need to enable incremental learning for DITA
make it easy to be adopted outside technical
writers
Integration is key to adoption
DITA is not legacy, it is modern web-enabled
technology

Thank you
Questions?
george@oxygenxml.com
@georgebina
http://www.oxygenxml.com

George Bina: DITA for Developers and GitHub for Technical Writers

More Related Content

What's hot (7)

Viewers also liked (17)

Similar to George Bina: DITA for Developers and GitHub for Technical Writers (20)

More from Jack Molisani (20)

Recently uploaded (20)

George Bina: DITA for Developers and GitHub for Technical Writers