This week an analytics ninja showed me how to use Google Analytics to track the values entered into a text field. It comes down to sending a dummy page name to Google Analytics, containing the value entered into the field. Google Analytics faithfully records a “page view” for that value, which you can then see in the analytics reports in the same way that you can see any other page view. Magic.
For example, let’s say you have a search box on a documentation page, allowing readers to search a subset of the documentation. It would be nice to track the most popular search terms entered into that field, as an indication of what most readers are interested in. If people are searching for something that is already documented, you might consider restructuring the documentation to give more prominence to that topic. And how about the terms that people enter into the search box without finding a match? The unmatched terms might indicate a gap in the documentation, or even give a clue to functionality that would be a popular addition to the product itself.
It turns out that you can track input values via Google Analytics. The trick is to make a special call to Google Analytics, triggered when the input field loses focus (
<input onblur="ga('send', 'pageview', 'my-page-name?myParam=' + this.value);" />
ga call sends a customised page view to Google Analytics, passing a made-up page name that you can track separately from the page on which the input field occurs. The made-up page name is a concatenation of a string (
'my-page-name?myParam=') plus the value typed into the input field (
my-page-name can contain any value you like. It’s handy to use the title of the page on which the input box occurs, because then you can see all the page views in the same area of Google Analytics.
Similarly, the part that contains the input text can have any structure you like. For example, if the page is called “Overview” and the input field is a search box, the Google Analytics call could look like this:
<input onblur="ga('send', 'pageview', 'overview?searchText=' + this.value);" />
This blog post assumes you have already set up Google Analytics for your site. See the Google Analytics setup guide. The Google Analytics documentation on page tracking describes the syntax of the above “ga” call, part of “analytics.js”.
Yesterday I was privileged and delighted to speak at a meeting of the STC Silicon Valley Chapter in Santa Clara. Thanks so much to Tom Johnson and David Hovey for organising the meeting, and thank you too to all the attendees. It was a lovely experience, with a warm, enthusiastic and inspiring audience. This post includes some links for people who’d like to continue playing with the APIs we saw last night and delving deeper into the world of API documentation.
The presentation is on SlideShare: API Technical Writing: What, Why and How. (Note that last night’s presentation didn’t include slide 51.) The slides include a number of links to further information.
The presentation is a technical writer’s introduction to APIs (Application Programming Interfaces) and to the world of API documentation. I hope it’s useful to writers who’ve had very little exposure to APIs, as well as to those who’ve played with APIs a bit and want to learn about the life of an API technical writer.
Here’s a summary of the presentation:
- Introduction to the role of API technical writer.
- Overview of the types of developer products we may be asked to document, including APIs (application programming interfaces), SDKs (software development kits), and other developer frameworks.
- What an API is and who uses them.
- A day in the life of an API technical writer—what we do, in detail.
- Examples of good and popular API documentation.
- The components of API documentation.
- Useful tools.
- How to become an API tech writer—tips on getting started.
Demo of the Flickr API
During the session, I did a live demo of the Flickr API. If you’d like to play with this API yourself, take a look at the Flickr Developer Guide (and later the Flickr API reference documentation). You’ll need a Flickr API key, which is quick and easy to get. Slide 23 in my presentation shows the URL for a simple request to the Flickr API.
There are more links to follow in the presentation itself: API Technical Writing: What, Why and How. I hope you enjoy playing with some APIs and learning about the life of an API technical writer!
Hallo fellow techcomm folks! Do you have a hobby?
Mine is fairly pedestrian. I like to go walking in the bush. It blows away the cobwebs. Well, actually, I often have to blow away the cobwebs myself. They festoon the pathways in the early morning. It’s best to keep your mouth closed when strolling in the Australian bush, or you’ll find yourself spitting spiders.
Sometimes a bird pops out and does something interesting, and I blog about it.
Of a dark winter’s eve I can perchance be found tickling the ivories. Perhaps significantly, other members of the household are usually to be found in the furthest corners of the house.
So fess up
What do you get up to when the pleasures of the pen pall? (Aside from avoiding sentences like that.)
For years I had a Calvin and Hobbes cartoon pasted above my desk. It showed Calvin’s father with a mangled bicycle, obviously the result of a bad stack. The caption read: “The secret to enjoying your job is to have a hobby that’s even worse.”
A fellow technical writer asked me this week about the documentation that developers need to do their jobs. He was thinking not of the guides people need when they want to integrate their systems with another organisation’s systems, but rather the internal guides developers may write for themselves about their projects and tools.
That’s a very good question. I’ve thought about it over the last couple of days, and pulled together a list of the types of developer-focused documentation I’ve come across. If you have any to add, please do!
The list is confined to documents relating to the role of software engineer/developer. It doesn’t include more general information that all employees need, such as human resources and facilities.
Information about the project and system they’re working on
- Who the people are: engineering team members, product managers, technical writers, stakeholders.
- Customers: Who they are and what they do, or would like to do, with the system or application that the team is developing.
- Goals: Mission, vision, goals for the upcoming month/quarter/year.
- Product requirements document for the system, application, or major feature that they’re working on.
- Design documents.
- Architectural overview, preferably in the form of a diagram.
- Comments in the code, written by their fellow developers.
Help with their development environment
- How to set up the development environment for the application/system that the team is developing.
- Guides to specific tools, whether built in-house or third party, including the IDE of choice, build tool, source repository.
- A pointer to the issue tracker used by the team.
- Guide to the team’s code review tool and procedures.
- Best practices for writing automated tests, and information about existing code coverage.
- Links to the team’s online chat room, useful email groups, and other communication tools used by the team.
- Where to go with technical and tooling problems.
- Coding style guides for each programming language in use.
- Guidelines for in-code comments: style; where to put them; how long they should be; the difference between simple comments and those that are intended for automated doc generation such as Javadoc; and encouragement that comments in the code are a Good Thing.
- Best practices for code readability.
Sundry useful guides
- Communication guidelines, if the developer’s role will involve significant liaison with third-party developers, customers, or important stakeholders.
- A map to the nearest coffee machine, preferably reinforced by a path of glowing floor lights.
Too much information can be a bad thing. :) I spotted this sign on a recent trip to Arizona:
A month ago I announced my project called “Tech Comm on a Map”. The idea is to help us see what’s happening in the world of technical communication around the globe. Tech Comm on a Map puts tech comm titbits onto an interactive map, together with the data and functionality provided by Google Maps.
When first announced, the map included data types for conferences, societies, and a grab-bag called “other“, which currently contains a couple of historically-interesting morsels.
Now I’ve added two more data types:
- businesses for commercial organisations specialising in tech comm, such as consultancies, recruiters, publishers, independent technical writers, and so on.
- groups for smaller groups and regular meetups of technical communicators, either as part of a larger society/association, or as an independent group.
Any groups or businesses to add?
At this point there are very few businesses and groups on the map. Do you have one you’d like me to add? Please add a comment to this post, including the following information for each item. The information will be publicly available on the map, via an information box that appears when someone clicks on the relevant circle on the map:
- Type: Conference, Society, Business, or Group
- Name of the business, group, society or conference.
- Website address (or an email address that people can use to get more information).
- Street address (this is essential, to position the item on the map).
- Start and end date for conferences, or meetup timing for groups (e.g. “First Wednesday of every month at lunch time”, or “Every Tuesday at 7pm”).
Note: Don’t add the names or addresses of any individuals, unless it’s your own name and address. We need to ensure we have people’s permission before adding their information in a comment on this post, or on the map. Any information you add here should be already publicly available on an organisation’s website or other publication.
Contributors to the project
Excited? I am. :) If you’d like to know more about the project, check out the introductory blog post. Soon I’ll write another post with the technical details of the APIs and other tools involved. In the meantime, here’s Tech Comm on a Map.