George Bina: DITA for Developers and GitHub for Technical Writers

George Bina [email protected] @georgebina #LavaCon

DITA for developers and GitHub for technical writers

@georgebina #LavaCon Copyright @ Syncro Soft, 2016. All rights reserved.


Using DITA and GitHub for both technical writers and developers



Can we all work together?

GitHub DITA

Developers Technical Writers



Can we all work together?

GitHub DITA




What do we need?

GitHub DITA


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



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




changes

Source repository


repository

review/edit modified documentation




changes •  review/edit modified

documentation

Source repository


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


repository




•  link to edit current documentation topic


repository





•  link to edit current documentation topic


repository


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


repository


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? [email protected] @georgebina http://www.oxygenxml.com

Leadership & Management

George Bina: DITA for Developers and GitHub for Technical Writers