Post a note under our blog aggregation requests if you want your blog added to our aggregator. Please provide the RSS feed URL and the title of your blog.
As I try to wrap my mind around the requirements of one of my current projects, I find myself struggling with the fundamental paradigm of single source publishing.
Consider Project Godzilla, as I’ll call it. Project Godzilla involves an API that plugs in requests from a lot of different product lines, thus serving as a kind of master API for dozens of products. The total possible JSON submitted in the request is quite large, since it accommodates so many potential products. But each customer will only use a slice of the JSON. As a result, the delivery engineers want to give custom (more)
Not many technical writers use YAML in their authoring tools. However, in the Jekyll environment, YAML is commonly used as an approach for creating a table of contents and other lists of content.
Most commonly, you store each item in your table of contents in a YAML file. You then iterate through that YAML file using Liquid syntax in order to push each item into a more complex HTML structure.
When I first learned that this is the approach to creating a table of contents in Jekyll, it struck me as odd. But as I have used it for a while now, I’ve found this is the best way t (more)
Here is a description of the API workshop I’m giving in Sacramento:Workshop on Documenting REST APIs
At its core, REST API documentation focuses on documenting requests and responses. You describe the various endpoints available, their methods, parameters, and other details. And you also document sample responses from the endpoints, usually describing each element and providing sample code.
In this workshop, you’ll learn the basics of REST API documentation. We’ll dive deeply into the following (more)
In postings for API documentation jobs, you’ll often see requirements like this:
“Ability to read code in one or more programming languages, such as Java, C++, or Python.”
Although your core task may be to document a REST API, most likely there will be numerous client implementations in different programming languages that you will also need to document.
The variety of programming languages creates challenges for technical writers, especially when employers want technical writers, from day one, to already be proficient in every language needed. In this new (more)
I'm now documenting an endpoint in a project at work that includes about 200 lines of code in a JSON object passed in the request body. There are various levels of key-value pairs and additionally nested objects inside the JSON object.
Most API documentation explains the parameters available for each endpoint. Usually the parameters are passed in the endpoint URL or, more common with POST methods, in the request body.
At the upcoming TC Camp, during a brief 5-minute feud activity, Marta Rauch and I are going to provide our perspectives on the following question:
How can I keep up with all the tools, technologies, info and other stuff to stay marketable? What happened to the good old days when all you needed to know was FrameMaker?
Admittedly, I can't help but feel caught in the same technological rat race, barely keeping my head above water. I do have some strategies that work somewhat for me, but there is a guy who (more)
In a recent discussion on the Techw-l listserv, an academic was looking to find advice about the "bleeding edge" trends in help authoring tools. Academics want to prepare students to succeed in the job market once they graduate, and since academics usually aren't focused on tools, this person was looking for guidance.
One of the commenters on the thread made a particularly astute observation about bleeding-edge tools. (more)
Here's the first video for my API documentation course:
Since I'm planning to make a lot more videos somewhat like this, I want to make sure I'm doing them right.My Setup
Here are a few details of my setup.
The TC Camp Unconference is just around the corner. Held January 22-23, 2016, in Santa Clara, California, this conference has been growing in popularity due to its unique unconference format.
The TC Camp Unconference doesn't include any pre-scheduled sessions or speakers. (Although there are some morning workshops available, these aren't part of the unconference format.)
For the unconference, attendees cast their votes on a wide range of topics. The org (more)
Every so often someone either proclaims that blogging is dead or asserts that blogging is alive and well. Recently someone noted that the 2015 vs. 2014 statistics comparison graph in my 2015 top posts analysis post looked interesting, so I decided to explore this comparison a little more to try to assess whether blogging (particularly my technical writing blog) was growi (more)
This past year I've been hearing a lot about addressing the whole customer journey, or developing a unified customer experience strategy. Companies need to have consistent content for every touchpoint with the customer, from the time the users are prospects to the time those users become customers.
When users are exploring a company, they may listen to a webinar, watch an overview video, explore a demo site, (more)
Every year I try to analyze the top posts on my site so that I better understand what information people are looking for. This analysis helps direct my blog efforts and lets me know what's working and not working. This analysis is just as much for me as any reader.
Compare this 2015 post with the Top 10 posts, podcasts, tweets of 2014 -- and what it all means.Top 10 posts written in 2015
Based on Google Analytics, these 10 posts written i (more)
I have often wondered why posts about "trends" tend to get massive reads. And I think I finally understand why.
One reason we read posts about trends is because we want to know whether our skills are evolving to match the changing technology landscape, so that we'll feel comfortable and secure in the future of our jobs.
If we find that technology is changing more rapidly than we can process, we might need to reorient our skillset, adjust our job functions or focuses, or alter our career direction to better align with the demands of the mark (more)
My API workshop will more or less follow the same content as my API doc course. This content is online and available right now.
For my presentation on Jekyll, here's the presentation title and description:
Writing tech docs like a hacker with Jekyll
Static site generators are a new breed of documentation tools that are much more common in engineering groups where developers contribute to the documentation.
Jekyll is one of the most popular static site generators, but it is highly simila (more)
A reader asks,
Our documentation team often gets blindsided by changes that developers make. We don't feel like we're kept in the loop with the updates and changes that developers are making to the application. How can we plug into the developer's worfklow?
Developers rarely make changes that aren't tracked in a system like JIRA. (JIRA is probably the most common issue tracking system, but your team may use something similar.) I'm betting they also follow an agile workflow.
My recommendation for plugging into the developer's workflow would (more)
Last week I attended a Write the Docs meetup in San Francisco, at Atlassian's stylish industrial-urban themed location. About 40 documentation enthusiasts (as they're called in WTD lingo) showed up, and we had an excellent panel discussion about creating documentation for startups.
I recorded the event and will be publishing the videos soon (after I see Star Wars, that is), but I wanted to make a quick blog entry to expand on an enjoyable conversation I had with someone as I was wheeling out my bike to catch the 8:40 Caltra (more)