TechWhirl Sponsors

About TechWhirl

TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.

For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.

Re: GitHub for writers

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".

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!

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.