GitHub for Writers (a Year Later)

It’s been about a year since our small writing team converted to a GitHub as writing environment (see GitHub for Writers). Several of us now write exclusively in Visual Studio Code (a.k.a, VSCode) and save to our documentation repository. Our Developers have provided tools to ensure good writing and style practices, and enable us to publish in HTML format on the company site.

I’m still in transition – writing in our old authoring tool and then making the same changes in VSCode (the dreaded “double-maintenance”). This is necessary because this documentation must be translated into two languages. Our Translation team is figuring out how to translate markdown in their new tool (while continuing to translate in the old tool). We won’t be in this situation forever, but I am looking forward to updating once in the future.

GitHub logo provided by pngimg.com

We had a few tool glitches at first. The linting and processing tools that worked so well in the Apple environment had problems in the WIndows environment. That made for some dicey release cycles. It took awhile to figure out the problem, but now the tools work for both. Other than that, the transition has been challenging and interesting.

More importantly, our users love having their tools and documentation located in one place (even though the documentation is currently a release or two behind the standard documentation, and lacks translation). During the transition, we try to keep them informed about the two sources and the differences. Once the transition is complete, we hope to implement a feedback loop, so users can provide improvements and suggestions. Then we’ll really be using the GitHub environment to its full advantage. Stay tuned!

Toolkit: GitHub for Writers

I am currently in the process of learning GitHub for writers. Our project management team has determined that customers will benefit from having access to enterprise development tools and documentation from the same interface, instead of navigating back and forth. To do this, we are using GitHub as the central repository for both the SDK and documentation. For writers, this means a big switch from our enterprise-level content management system and feature-rich authoring tools to something less sophisticated (like going from a loaded Cadillac to a stripped down Prius, even when you know it’s the right thing to do).

GitHub logo provided by pngimg.com

The challenge has been switching from our current authoring environment, at the same time that agile development, releases, and micro-deliveries march on. Once the migration is complete, and we’re in the new environment, I think everything will be fine. Knowing that our customers will be better served is a big motivator for getting through the temporary disruption. The developers have been very supportive and enthusiastic about the change, and have developed tools and processes that provide some of the tools that we rely on in our authoring environment.

I’m looking forward to the day that our project is fully migrated, and that I’ve developed enough skill so my brain doesn’t contort every time I do anything. Then I can enjoy the benefits of being able to collaborate on projects with folks all over the world (both personal and professional), focus on the writing rather than production, and access the files from anywhere via a browser. And who knows, we may find that what seems primitive, will turn out to be more sophisticated than we think!