Re: Is this the future of technical writing?

[Michael McCallister <workingwriter -at- gmail -dot- com>]

Interesting piece. Can't say I'd ever heard of AsciiDoc before, so I
learned something from the article too!

This article is more about producing documentation (and books) with
developers collaborating with writers and other developers, so I don't know
how relevant this process will impact our day-to-day lives. Might be worth
experimenting with, though.

To Julie's point: I think I did start reading the Git documentation when
our devs moved there a year or so ago, and I'll heartily concur with Julie.
Considering that Git, the program, was originally written by Linus
Torvalds, I'll guess his comments form the base of those docs.

Fortunately, judging from this page alone (not any of the more
advanced/troubleshooting material), the *Pro Git *text is pretty readable:

http://git-scm.com/book/en/v2/Getting-Started-Git-Basics

Here's a nice definition from that page:

"The mechanism that Git uses for this checksumming is called a SHA-1 hash.
This is a 40-character string composed of hexadecimal characters (0â9 and
aâf) and calculated based on the contents of a file or directory structure
in Git."

Cheers,
Mike (who still aspires to someday write an O'Reilly book)



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

On Tue, Oct 28, 2014 at 9:40 AM, Julie Stickler <jstickler -at- gmail -dot- com> wrote:

> Oh sweet baby Jeebus I hope not.  I'm not sure if he's the fellow that
> wrote the base Git documentation or not (http://git-scm.com/documentation
> ),
> but I can tell you, it's atrocious.  I have struggled for the past two
> years to learn my way around Git. I have read and re-read their
> documentation as I struggled to resolve issues I've had with Git, and  as
> many times as I've read it, half of it still doesn't make any sense to me
> because it's so full of jargon and makes huge assumptions about what the
> audience understands.   And I don't think it has anything to do with the
> fact that I'm a technical writer and not a developer. because many of our
> developers and QA engineers seem to have trouble doing more than the basic
> functions in Git.  We rely a lot on our couple of in-house Git experts to
> troubleshoot problems.
>
> Honestly, I don't care what tool chain you used to write your doc, if the
> doc that you produce is not helpful to your users, then you've wasted
> everyone's time.  Yours as a writer, and your audience's as a reader.
>
>
>
> On Tue, Oct 28, 2014 at 10:11 AM, Cardimon, Craig <ccardimon -at- m-s-g -dot- com>
> wrote:
>
> >
> >
> https://medium.com/@chacon/living-the-future-of-technical-writing-2f368bd0a272
> >
> >
> > Thoughts?
> >
> >
> > Cordially,
> >
> > Craig Cardimon | Technical Writer
> > Marketing Systems Group
> > www.m-s-g.com<http://www.m-s-g.com/>
> >
> >
> >
> > Information contained in this e-mail transmission is privileged and
> > confidential. If you are not the intended recipient of this email, do not
> > read, distribute or reproduce this transmission (including any
> > attachments). If you have received this e-mail in error, please
> immediately
> > notify the sender by telephone or email reply.
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > Read about how Georgia System Operation Corporation improved teamwork,
> > communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >
> > You are currently subscribed to TECHWR-L as jstickler -at- gmail -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
> >
>
>
>
> --
> Julie Stickler
> http://heratech.wordpress.com/
> Blogging about Agile and technical writing
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Read about how Georgia System Operation Corporation improved teamwork,
> communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as workingwriter -at- gmail -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
>

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l

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

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