RE: Git [was RE: Windows VM on Mac ?]

Subject: RE: Git [was RE: Windows VM on Mac ?]
From: "Janoff, Steven" <Steven -dot- Janoff -at- hologic -dot- com>
To: "mbaker -at- analecta -dot- com" <mbaker -at- analecta -dot- com>, 'Michael McCallister' <workingwriter -at- gmail -dot- com>, "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 22 Mar 2017 19:05:32 +0000

That's awesome, Mark -- definitely going to take some thought.

Thanks so much,


On Tuesday, March 21, 2017 9:22 PM, Mark Baker wrote:

I think that the design virtues of the paper world -- which were largely the design virtues of a static object intended for long duration -- and those of the digital world -- a dynamic feed intended to be updated when needed and deleted when obsolete -- are very different.

So much of what makes a book look good have to do with pagination -- fitting words and pictures into a set of fixed sized pages with fixed sized fonts.
All of this is irrelevant on the Web. But all sorts of other things matter on the Web. Web content has behavior. It has links. It is expected to be current at all times.

And Web content is used differently. Information snacking is much more common with web content because people do not feel the need to stock up on information before setting out on a task. They expect to be able to find out anything they need when they need it. The expect to be able to ask questions and get prompt answers.

All of this calls for content to be written and organized and presented very differently. Readers will react to content based on its total set of virtues. Looking good is still a virtue, but it is a much simpler virtue on the Web, and all of the other virtues weigh in the balance as well.

I think that Docs as Code is a response to this, and I expect/hope that it will continue to make progress against the heavyweight monolithic systems in current use. But docs as code needs to mature a lot to achieve its full potential -- to provide all the virtues that readers are looking for, including looking better than it does now. (But again, looking good on the Web is a much easier problem than looking good on paper because no pagination to worry about.)

Docs as code simplifies the documentation process with a hands-off management and build system. But there is a limit to how much hands-off management and build you can do with the limited structure provided by Markdown and Jekyll. Git is not a satisfactory repository solution if you start to need to do complex or tightly coupled management tasks on your content.

Version control systems don't manage relationships within and between the files they manage. They leave that entirely to the build system. A CMS actively manages those relationship, allowing writers to manipulate them directly. This is a huge difference. To get more complex projects out of the CMS world, you have to get the management of relationships out of writer's hands and delegate them entirely to the build system. That requires enough structure in the content to delegate all relationships to the build system.

Real code is far more highly structured than Markdown, meaning you can do far more build automation, which means you don't need hands on management like you find in a CMS in the content world. To handle similarly complex problem in a docs as code environment we will need much more structure in our content. Not DITA or DocBook kind of structure, but something quite different. We've know how to do this for a quarter of a century. Pagination has always been its weak spot, though. Its time may finally be at hand. I have a book scheduled to come out later in the year that explains it in detail.


-----Original Message-----
From: techwr-l-bounces+mbaker=analecta -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+mbaker=analecta -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Janoff, Steven
Sent: Tuesday, March 21, 2017 7:03 PM
To: Michael McCallister <workingwriter -at- gmail -dot- com>; techwr-l -at- lists -dot- techwr-l -dot- com
Subject: RE: Git [was RE: Windows VM on Mac ?]

You know, looking at GitBook, this makes me wonder... and maybe this has been dealt with before on this list... is this kind of the future of documentation?

In some ways it looks primitive compared to the professional docs a lot of us put out every day. And there is certainly room for design improvement -- information design and graphic design.

But you have to wonder if things will all go this way eventually. I suppose wiki docs are like this.

Mark Baker, what do you think?



On Tuesday, March 21, 2017 2:19 PM, Michael McCallister wrote:

Hey all,

For those of you who might want to play with Git, GitBook ( is a repository for random pieces of documentation. Up to five writers can collaborate on a single public-domain or open source project for free, Click the Explore tab to read current projects. Could be a place to test multi-writer conflict issues

I have not worked on a project here, though I've thought about it. The devs at work use Git for source control, and I do keep HTML, Word and PDF docs in my own repository, away from the code.

Manning publishing keeps a GitLab installation for its authors to use if they're so inclined. GitLab and GitHub are competing public Git repositories.

Mike McCallister

Mike McCallister
Available now: *Build Your Author Platform: The New Rules* <> (w/Carole Jelen) Notes from the Metaverse:

Visit TechWhirl for the latest on content technology, content strategy and content development |


You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @

Re: Git [was RE: Windows VM on Mac ?]: From: Peter Neilson
Re: Git [was RE: Windows VM on Mac ?]: From: Elisa R. Sawyer
Re: Git [was RE: Windows VM on Mac ?]: From: Michael McCallister
RE: Git [was RE: Windows VM on Mac ?]: From: Janoff, Steven
RE: Git [was RE: Windows VM on Mac ?]: From: mbaker

Previous by Author: RE: Git [was RE: Windows VM on Mac ?]
Next by Author: Re: Windows VM on Mac ?
Previous by Thread: RE: Git [was RE: Windows VM on Mac ?]
Next by Thread: Re: Git [was RE: Windows VM on Mac ?]

What this post helpful? Share it with friends and colleagues:

Sponsored Ads