Recording of Version Control, Writers, and Worfklows by Richard Mateosian
You can watch the recording of Richard Mateosian's November 2015 presentation to the STC Silicon Valley about version control, writers, and workflows.
Question: How long does it take to ramp up on your Jekyll theme?
Using Jekyll for documentation will probably require more time and effort than a commercial out-of-the-box authoring tool. On the other hand, Jekyll may be more suitable to you if you're customizing a doc website, want a developer's workflow, or simply want the freedom of using open source tools and working in code.
Swagger UI probably the coolest thing I've done in API docs
Swagger should be a feature of every REST API doc set, since it connects with the user's primary desire to try out a product in order to learn it.
10 realizations as I was creating my Swagger spec and Swagger UI
As I've been configuring the Swagger spec file and UI for one of the APIs I document, I had a few realizations that I wanted to share. Some realizations involve understanding the Model versus Model Schema part of the Swagger UI, the syntax of using JSON references within the spec, how validation works, and more.
Guest Post: Could Software Perform Technical Writing? by Robert Desprez
In this guest post, Robert Desprez looks at the possibility that advanced technology may replace the need for technical writers. Desprez explores a recent book by Martin Ford (Rise of the Robots) on the subject.
Single sourcing the Swagger spec and main documentation using Jekyll
You can use Jekyll to populate variables in both your Swagger spec and main documentation. This allows you to single source your content into both of these outputs in a more efficient way.
Version 4.0 released for the Jekyll Documentation Theme
Version 4.0 of the Jekyll Documentation Theme now supports multiple projects inside the same theme. This allows you to use the theme for any number of documentation projects with any number of authors.
Planning my API doc course
As I prepare to record my API doc course, I'm finalizing a few thoughts about the content, setup, and other details.
Upcoming Write the Docs Meetup
Write the Docs has a meetup in downtown San Francisco on Dec. 17. The topic is on creating documentation for startups, and will feature a panel discussion. You can ask questions ahead of time, or come prepared to ask them at the meeting.
My pros and cons of using Jekyll for documentation
As with any help system, there are some pros and cons with using Jekyll for documentation sites. Since I usually emphasize the pros of Jekyll in my posts, I wanted to balance out the perspective a bit by listing 10 cons and 10 pros.
Can you replace a CCMS with version control such as Git or Mercurial?
Instead of resorting to an expensive Component Content Management System (CCMS) to facilitate content re-use and collaboration across projects, you can probably get by with some basic version control tools that software developers have been using to collaborate on projects for years.
Tell me about your career as a technical writer...
Technical writing is a pretty awesome career. You'll probably enjoy it unless you dislike writing, aren't technical, hate working in team environments, and prefer to write content that pressures people to buy crap they don't need.
Why incremental regeneration in Jekyll 3.0 is such a big deal
Jekyll's incremental regeneration continuously rebuilds your project each time you save a change. This can help you quickly identify errors and fix them immediately, since the time between when you make the error and when you're notified of the broken build is reduced.
Increase efficiency 24 times faster when fixing errors — implications for technical writers on agile teams
If you want to influence developers to make changes to code (such as with UI text), it's 24 times easier for developers to make the changes if you tell them the same day they code the feature than if you wait a few weeks later. This means technical writers should keep pace with the features coded during each sprint.
Podcast: Spec-driven Development of REST APIs, with a focus on RAML -- interview with Michael Stowe
Spec-driven development is an approach to developing REST APIs by first describing and prototyping the API through a specification file (such as RAML or Swagger), and then coding the API. The spec not only serves as a contract for the API's development, it can also generate interaction documentation, unit tests, client SDKs, and provide other benefits.