Adobe FrameMaker

Get new posts delivered straight to your inbox.

Subscriber count: 4,300

Stitcher radio

Adobe FrameMaker

Upcoming presentation in Denver: Docs-as-code tools and workflows (March 9, 2018)

Jan 29, 2018 • api-doc

I'm giving a presentation to the Rocky Mountain STC on "Docs-as-code workflows and tools" on March 9, 2018. The docs-as-code approach is most common in the developer doc space. In this presentation, I'll explore the upsides and downsides of treating documentation as software code, and what details are involved in adopting engineering tools, workflows, collaborative processes, and other practices. The presentation will include a number of concrete examples and demos.

The event is hosted through the Rocky Mountain STC group. You can view the event details here: Docs-as-code workflows and tools.

Event description

Here’s the event description:

Docs-as-code workflows and tools

If you plan to involve developers in writing and editing documentation, you might have more success by adopting the same tools developers use for software coding. This approach is often called “docs-as-code.”

To treat docs like code generally means doing some of the following:

  • Working in plain text files (rather than binary file formats like FrameMaker or Word).

  • Using an open-source static site generator like Sphinx, Jekyll, or Hugo to build the files locally through the command line (rather than using a commercial program such as FrameMaker or Microsoft Word).

  • Working with files through an IDE such as Atom, Sublime, or another text editor (rather than relying on commercial tools with proprietary, closed systems that function like black boxes).

  • Storing docs in a version control repository (usually a Git repo) similar to how programming code is stored (rather than keeping docs in another space like SharePoint or a shared drive); also if appropriate, potentially storing the docs in the same repository as the code itself.

  • Collaborating with other writers using version control such as Git and GitHub to branch, merge, push, and pull updates (rather than collaborating through large content management systems or SharePoint-like check-in/check-out sites).

  • Automating the site build process with continuous delivery to build the web output from the server when you update a particular branch (rather than manually publishing and transferring files from one place to another).

  • Running validation checks using custom scripts to check for broken links, improper terms/styles, and formatting errors (rather than spot checking the content manually).

In short, treating docs like code means to use the same systems, processes, and workflows with docs as you do with programming code. In this presentation, we’ll dive into each of these aspects of docs-as-code in depth and explore the advantages and disadvantages of the approach.

Event details

Location:

Metropolitan State University of Denver: Room CN 113
1198 11th Street
Denver, CO 80204

Time:

Fri, March 9, 2018
6:00 PM – 8:30 PM MST

Cost:

The cost is between $0 to 10, depending on whether you’re a student or chapter member. You can register for the event through Eventbrite.

follow us in feedly


Get new posts delivered straight to your inbox.

Subscriber count: 4,300

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include the following technical communication topics: Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, and certificate programs. I'm interested in information design, API documentation, visual communication, information architecture and findability, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.