[Author Prev][Author Next][Thread Prev][Thread Next]
[Author Index (this month)][Thread Index (this month)][Top of Archive]

Re: GitHub for writers

Subject: Re: GitHub for writers
From: Mark Giffin <mgiffin -at- earthlink -dot- net>
To: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
Date: Fri, 06 Sep 2013 14:53:14 -0700

Hi Kevin,

I'm not using Prose but I was the original poster (and I use GitHub all the time for programming code). This GitHub/Prose setup is definitely not ready for normal tech pubs use, so it's not going to replace your MadCap Flare anytime soon. I mainly posted it as an example of one of the new lightweight authoring workflows that are being experimented with in the world. I think it behooves tech comm people to at least keep an eye on such things. A lot of people are experimenting with these things and I believe they will affect our community at some point in the future.

By the way I believe you can use GitHub only on the GitHub site if you want to, without using git at the command line to do a "push" or a "'pull request".

Another one I'm keeping an eye on is the OReilly Atlas project:

http://atlas.labs.oreilly.com/

It works roughly like this: You author your docs in a lightweight markup (Asciidoc) and store them on GitHub (there it is again!). You can collaborate with others (editors, reviewers etc.) using the GitHub tools. Then when you want to publish, they have a custom PDF output toolchain that makes a very nice-looking PDF that looks very much like an OReilly technical book (like say /JavaScript, The Definitive Guide/). It's set up for book publishing in PDF form. I don't think there is much control over the look of the PDF at this time. There is no webhelp-style output that I know of. And I don't know the prices yet.

For those who are interested in technical details, under the covers the output toolchain transforms the Asciidoc into DocBook XML, and from there uses OReilly's DocBook toolchain they have been using for many years for their books. They use Antenna House as their PDF processor. I believe they are using CSS3 to markup up the XML for PDF output, and not XSL-FO. An XSL-FO programmer like me doesn't like to hear that, but things change!

Mark Giffin
http://markgiffin.com/



On 9/6/13 9:02 AM, McLauchlan, Kevin wrote:

If I understand correctly, you download and install an app on your local PC, that lets you create a local repository.
I'm not quite sure what that gives you, except that you can then "Push to github" which lets everybody in the world see your employer's/contractee's code-or-docs, unless you pay for a private account.

So, to test out the system in any real way (to find out if the workflow and other constraints agree with your situation), you need to pay to play.

As a rather committed user of MadCap Flare (it's our corporate standard for techpubs), I'm not clear on what Prose will do for me... since I haven't gotten there yet (see the pay-to-play step above).

I guess I can afford $7/month to try it out (GitHub, with or without Prose), off the public stage, but I'd need to take advice from management as to whether I could put company doc source onto an uncontrolled service that I'm privately paying for. (Chances of that being agreed are perilously close to zero.)

The other option would be to create an entire bogus set of docs that mirrored the functionality (size, shape, templates, linking, etc.) of the employer-owned docs, but without the content. I include "size" in that list, because we know that increasing numbers of files and the size-and-number of attached things like graphics can have a big effect on daily operation, when there's uploading and downloading involved. It wouldn't be fun if I basically had to stop work every time I did a push or pull, but I'd need to test big, in order to find out. Unless somebody already has and can say??

Of course, I already have to stop work for more than 20 minutes, each time I run a build-publish cycle in Flare... per project, so frequent pauses/slowdowns would not be unprecedented, but we don't want to add more without major benefit. The Flare instance that is building/publishing is 100-percent committed to that. Any other Flare instance on the same computer slows to a crawl for the duration. If you tell two instances of Flare to publish simultaneously, you can go for a leisurely, extended lunch.

I mean, this is interesting and all, but I'm not clear where/whether I should start with GitHub for techpubs.

The other option is wait-and-see until the company gets going with their setup, and then see if techpubs fits in among the coder infrastructure any better than we did when the content/versioning/bug system was MKS (or ClearCase, before that) - which was "not all that well"... sorta like a wart on an appendage. :-)

Can somebody who is using GitHub and Prose in anger please lay out your workflow and what other tools you use?

Thanks.



The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.

Learn more: http://bit.ly/ZeOZeQ

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

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

References:
GitHub for writers: From: Mark Giffin
Re: GitHub for writers: From: Tony Chung
Re: GitHub for writers: From: John G
Re: GitHub for writers: From: Robert Lauriston
Re: GitHub for writers: From: punit shrivastava
Re: GitHub for writers: From: Robert Lauriston
RE: GitHub for writers: From: McLauchlan, Kevin

Previous by Author: GitHub for writers
Next by Author: Re: Keyboards revisited
Previous by Thread: RE: GitHub for writers
Next by Thread: Prof/Tech Communicators' Perceptions of Usage Error (Survey Invitation)

[Top of Archive] | [Author Index (this month)] | [Thread Index (this month)]

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

Sponsored Ads