Github / Jekyll / Tom Johnson’s Documentation Theme
This setup combines
- Github as data repository
- Jekyll as static data CMS
- a theme tailored for documentation
- and in the background a web server
Example: this site with a transformed NewsML-G2 Quick Start Guide
Comments from setting it up and using it:
- The template engine Liquid is powerfull in merging templates and dynamic content but does not support the management of pages (files).
- Therefore all the menues (top navigation bar and sidebar) must be defined manually: first a page (file) must be created and named and then its permalink has to be added to the …bar. This editing for the YAML parameters is not trivial.
- A basic page template issue is: if they are simple they are flexible but need extensions in many cases, more elaborate templates need less or no extension but also focused on a specific layout.
- A user has to understand the interaction between Jekyll, Liquid and the Theme …
- … but the documentation of such a system is hard to follow: some features come from Jekyll, some from Liquid, some from the theme and a few from Github. One has to read three documentations first to be able to find the source of problems. And: some documentations are not up-to-date.
- How to edit content: there are two options: a/ to edit the file in the Github UI b/ to create a local instance of Jekyll + Theme and transfer the pages between the local and the Github repository by git means. The not so nice features of these options are: re a/ the Github UI is not overly supportive for editing, re b/ this requires a lot of knowledge of the used components - and Windows is not well supported.
My summary: in a first step the theme must be a/ understood and b/ adjusted to IPTC needs. The easier way of editing the content is in the Github UI - with a low practical support of the editing person. The management of files by git and Github is easy.
GRAV / Learn2 Theme for documentation
In late spring 2016 I came across the static data CMS GRAV, the basics are very similar to Jekyll and I started to check how it could be used for IPTC purposes. For this reason I’ve set up a test site including a transformed NewsML-G2 Quick Start Guide
This setup combines
- the file system of a web server as data repository
- GRAV as static data CMS
- a theme tailored for documentation - Learn2 used by the GRAV documentation
- and in the background a web server
Comments from setting it up and using it:
- GRAV is delivered as ZIP package, needs to be decompressed on the web server
- After installing the files the site’s URL can be called with an administration user interface
- By that UI basic settings and the pages of the CMS can be edited
- Template related user experience: a template matching exactly or closely the user’s needs is if help as adjusting the internal structure is not a cheap trick. But GRAV templates are more flexible than Jekyll templates as the structure of the content is auto-managed by GRAV (themes), it is only required to use a specific naming for the pages.
- Page editing experience: the GRAV-internal user interface strongly supports the user. The pages are shown in a hierarchial tree and can be moved around, the file names are automatically adjusted. And the editing of content is supported by us WP-like toolbar of the editor.
My summary: in a first step the CMS must be installed and its theme must be understood. The management of pages and their editing is quite easy. The management of the files is done by the administrative user interface.
Doc-To-Help system for technical editors
I’m using the Doc-To-Help systems for some documentation projects, one of them is the IPTC Photo Metadata User Guide, published last week.
This system provides/requires:
- the local file system of a (desktop) computer as data repository
- Word for editing the content
- Doc-To-Help for creating the output from the Word document - either as HTML or PDF.
Comments from my user experience:
- If Word is the standard document editor then using Doc-To-Help is almost a no brainer …
- … only the way of implementing the elements for creating a structure in the deliverable must be learned.
- Doc-To-Help creates all targed files on the local computer …
- … these files must be transfered by e.g. FTP to the web server.
My summary: Doc-To-Help needs to be installed as Windows application, all specific Word tools are added by that. The management of the final hierarchy in the flat Word document needs some abstract strategy.The files of the deliverable are managed locally, then they must be transferred to the production web server.
Footnote
Tom Johnson, the maker of the Jekyll Documentation theme, is a professional technical writer at Amazon. On his private web site he referred to and commented a quite interesting survey about what systems are used by professional technical writers. Have a look at that
Finally …
That’s my experience, that’s my view, consider it as a starting point for discussion.
Sorry for the typos, I’ve created this page in the last minutes prior to the IPTC Autumn Meeting 2016.
Best,
Michael
(Michael Steidl, IPTC Managing Director)
END