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

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

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.

Mark

-----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?

Thanks,

Steve


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 (
https://www.gitbook.com/) 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.

Cheers,
Mike McCallister


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

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and
content development | http://techwhirl.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as mbaker -at- analecta -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
http://www.techwhirl.com/email-discussion-groups/ for more resources and
info.

Looking for articles on Technical Communications? Head over to our online
magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public
email archives @ http://techwr-l.com/archives

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Follow-Ups:

References:
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

Previous by Author: RE: HyperDrive Thunderbolt 3 USB-C Hub for new MacBook Pros ?
Next by Author: RE: User Documentation in Agile Development Teams
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