• October 2016
    S M T W T F S
    « Sep    
  • Facebook

Zooming out and in with navigation

Android reference documentation

Here’s a short (silent) demo of how the Android navigation moves horizontally left to right:

I have no idea how the sidebar is assembled on a technical level. It seems like a nightmare to maintain, honestly. And from a usability perspective, it doesn’t entirely orient me to where I am in the documentation. (The documentation is probably too massive for me to feel comfortable to understand its entirety through a simple sidebar hierarchy.) But the sidebar combined with the breadcrumb does as good a job as one can expect. And it does give me an idea of where I am without presenting a massive, never-ending list of sidebar items.

For example, if I view the Creating an Android Project topic, I can see from the breadcrumb exactly where I am in the site hierarchy: Develop > Training > Getting Started > Building Your First App.

The higher level items (“Develop > Training”) don’t mean a tremendous amount to me. But “Getting Started > Building Your First App” does. And if this isn’t the right topic but perhaps another tutorial is, I know that I can go back up to “Training” to see other tutorials.

Overall, the Android site is really a work of art. It’s not perfect, but the site does an amazing job at providing a seamless, organized, and thorough arrangement of a mountain of documentation content.

At my work at Amazon with the Developer Portal, we’re in the middle of a site transition from an older CMS to a new, home-grown platform. The site doesn’t have nearly the same amount of content as the Android doc site, but there are a number of products, many of which overlap with their documentation. For example, whether you’re submitting a Fire TV app or Fire Tablet app, you go through the same app publishing steps.

Much of the tech doc content is still in the older CMS. You can see an example with the Fire TV documentation here. The built-in navigation on the left doesn’t provide control at a sufficiently granular level for technical documentation. So as an interim measure, we built another doc navigation sidebar on the right that helps improve the navigation among pages in a documentation collection.

If you look at the bottom right, at “Documentation Categories,” you’ll see that I’ve arranged the content into various groupings:

  • Getting Started
  • Catalog Integration
  • Fire TV Web Apps
  • Fling SDK
  • Appstore Publishing

(By the way, the end-user documentation for Fire TV is on an entirely different site, so there’s no need to distinguish between third-party developer documentation, which is for developers building apps for Fire devices, and end-user documentation, which is used by mainstream users who use Fire devices.)

The content in the previous CMS was more or less flat, like a wiki. Beyond some high-level categories, the principal means of navigating from one topic to another in the documentation was through in-page links. Although in-page links are helpful, they don’t necessarily facilitate the ability to take in the available information in the documentation as a whole, nor do they help you understand the context of the information at a macro level.

I believe that each documentation group should have a persistent sidebar that allows users to navigate all topics within that documentation group. But by “documentation group,” I don’t mean a massive, all-encompassing list of documentation that almost looks like a sitemap. Instead, I’m referring to a logical collection of topics, somewhere between 10 and 30 topics, which fit together.

Some groupings are obvious. For example, all documentation related to the Fling SDK naturally fits together in a group. The “Fire TV – Getting Started” category is a little more ambiguous. It’s kind of an introductory/miscellaneous-development category.

Eventually, as the site continues to evolve, these documentation groupings will take shape in the new look and feel of the site, and hopefully our navigation controls will become more intuitive and seamlessly woven throughout the site.

But regardless of the actual design it eventually conforms to, the ability to zoom out and in within documentation is important. And understanding just the right magnification level that users need to see is an art. If you have too many topics in a sidebar, one ignores the sidebar because it’s just noise. Too few, though, and it’s hard to see where you are or what else is out there. Building the zoom-in/zoom-out controls within the sidebar seems like a best practice for finding a balance between the two macro/micro extremes.

Kanban may be a better fit than scrum when you support large numbers of engineers


During the last STC meeting on agile, I was chatting with a fellow writer about whether agile fit his role at his work. He said that because he supports about 80 engineers, kanban was a better fit for him than scrum.

I wrote previously about kanban here and here. Both kanban and scrum are two different approaches to agile.

The main difference between kanban and scrum is that scrum organizes work into two week sprints, with points assigned to each item. The scrum team is expected to complete a specific number of points before the sprint ends.

With kanban, instead of organizing the work into sprints, you organize the work into three main buckets: to-do, in progress, and done. You limit the number of items in progress to just a few (for example, three). When you finish an item in-progress, you move another item from to-do bucket into the in-progress bucket.

Kanban doesn’t have two week sprints or velocity calculations or demos. It’s simply a means of limiting the number of items (limiting the “flow” through visual cards) so you can focus more clearly on completing items that need focus. It’s a way of avoiding the scatterbrained feeling of working on 5 tasks all at once and accomplishing nothing.

Kanban is a better fit for me because of my work environment and content publishing role. When I worked at 41st Parameter (a startup bought by Experian), I was tightly grouped into two engineering teams and attended their daily standups, sprint demos, retrospectives, and other scrum meetings.

At Amazon, I support a large number of engineers working in the Appstore group. I’m not sure how many engineers are actually in the Appstore group, but for my focus with Fire TV, there are more engineers than I can know and keep track of.

Some teams work on features that require documentation, while others don’t. For those that do, often the groups will generate the documentation on an internal wiki page, and I’ll convert the content into formal documentation and publish it on our Developer Portal.

In addition to this content publisher role, I am loosely integrated into one scrum team where I author original content from scratch. Although the team follows scrum, I’m finding that it’s better for me not to participate in all the scrum activities but instead to keep my ear to the project and pop in and out when there are features requiring documentation.

At large companies, or in scenarios where small numbers of tech writers support vast armies of engineers, it might not be practical for tech writers to integrate tightly into the scrum teams as other engineers do. If you have to support 5+ scrum teams, your week’s bandwidth will be consumed by meetings that have a low signal-to-noise ratio, and little value for the time expended.

Much of an engineering scrum team often gets caught up in engineering tasks that don’t actually impact the documentation, since the code doesn’t get exposed to users nor does it affect users in ways that would require documentation.

For example, a user may not care about the inner workings of Feature X – the user just needs to know how to configure Feature X. But engineers will spend 80% of their time building Feature X, and talking about bugs they found in testing Feature X, and the best libraries and approaches for integrating Feature X, and so on. The writer needs only to come in at the end to describe Feature X and explain how to configure it. Would it really be efficient to attend meetings where engineers discuss at length how to build and test and deploy and troubleshoot Feature X?

If you’re not regularly involved in an engineering scrum, you need another way to stay abreast of what’s going on, so you won’t miss those times when something does actually come up that requires documentation. I’ve found it’s helpful to establish contact points with key players who have their pulse on important features to document. The key players should understand what various engineering teams are working on, when the release dates are, and who you should contact to get more information. Regular meetings with these key players around documentation priorities and needs can replace the need to attend countless scrums.

One of the key benefits of agile is that it gives you deadlines to [try to] finish your work. Your goal is to complete the task before the sprint closes. While deadlines are generally a good thing, this two-week sprint model has some problems:

  • You either finish your task early and have idle time (rarely the case).
  • You don’t finish your task and then feel bad for not completing your target.

Most teams over-estimate the amount of work they can complete during the sprint, not properly factoring in the overhead of corporate email, meetings, and other interactions. As a result, usually teams over-allocate the work and then feel bad about themselves when they don’t meet their goals. Project managers get upset and try to “unblock” what might be causing the slow-downs. During these time crunches, engineers then don’t have time to review documentation because they’re heads-down trying to meet their over-estimated sprint goals.

Kanban doesn’t impose deadlines. Theoretically you could spend an eternity working on one task that always remains in progress and never moves to done. But the reality is that you work on items with a regular cadence, and finish them when you finish them. You don’t feel the let-down when your sprint ends and you haven’t finished all your tasks, because you don’t have sprints. Instead, you just keep cranking away at those tasks in the to-do bucket.

I’m not a kanban expert, and I have plenty of room to improve my role. JIRA has the ability to configure kanban boards instead of scrum boards, which I think might really be a better fit for documentation.

My role has certainly shifted from the tech writer who writes everything to the tech writer who publishes everything (and writes original content only for some products). I like the hybrid role, as it gives me exposure to a large number of technologies. And I feel that playing the content curator/publisher role allows me to scale. Still, it’s an interesting new dimension to my work. With this role, it seems that kanban is a better fit for me than scrum.

Back to Top | Comments Off on Kanban may be a better fit than scrum when you support large numbers of engineers

How can technical writers thrive in agile environments? Event recording and details

Audio Recording

Listen to the recording:

You can download the MP3 file, subscribe in iTunes, or listen with Stitcher.

Agile panel event description

Here’s a description of the agile panel event:

How can technical writers can thrive in agile environments?

Most engineers in IT departments follow an agile scrum process: they track issues in sprints, assign and scope story points, meet daily to provide short updates on their work, and release updates every 2-3 weeks.

Technical writers who work with engineers usually find that being productive requires them to become familiar with the engineer’s agile scrum workflow. Whether you want to keep abreast of engineering work, factor in time for doc reviews during the sprint, or have documentation be managed like other IT work, you need to know how to integrate or work with the agile scrum workflow.

In this chapter meeting, we will have a panel discussion about how technical writers can thrive in agile environments. (See the STC SV event post for more details.)


The following 5 people were panelists:

Bonnie Clark has almost 20 years of experience in the technical communication field. She is currently a Director of Technical Publications at FICO, a leading analytics software company.

Rosemary Picado is the Documentation Team Lead at Sumo Logic, and works with agile and non-agile teams within the company to document their cloud-based log management platform. Formerly at Recommind, she transitioned from Tech Writer to Scrum Master while the platform was being re-architected, learning the value of Agile first hand, and how the skill sets intersect and complement each other.

Daniel Doornbos has been a technical communicator since 1982. He most recently worked as a Senior Technical Writer at HEAT Software on its IT Service Management product. The company is in the process of transitioning to agile development.

Jane Wilson leads the technical writing team for GE Digital’s Applications Engineering group. GE Digital develops in an Agile environment, and, as the team has grown, she has developed processes for fitting writers and the writing process into Agile methodologies. Along the way, she became a certified scrum master. Jane belongs to the East Bay and Atlanta chapters, and she currently serves on the STC Board as Treasurer.

Gina Blednyh is a Staff Technical Writer at Salesforce. She’s worked in an Agile environment for almost six years. She’s also been a scrum master for both a writing team and an engineering team and is an Agile convert.

I moderated the panel.

Questions discussed

Here are some of the questions about agile and tech comm that we discussed:

  • Should documentation be managed as items in an engineering sprint?
  • Should doc reviews be assigned story points?
  • Do you still create a documentation plan at the project kickoff if you are following an agile scrum process?
  • How can you keep pace in documenting features during the sprint if the features don’t get finished until the end of the sprint?
  • How can you reduce the tedium of daily standups when engineers seem to rattle on endlessly about coding issues?
  • How can you stay updated about JIRA items when engineers don’t take the time to articulate the issue but rather hastily add a quick title that only they and other engineers who are already familiar with the issue understand?
  • How can you persuade engineers to dedicate time for doc reviews if there’s no points allocated for the work in the sprint?
  • Logging bugs changes the role tech writers play on teams. Should tech writers log bugs when they find them, or simply send emails to the QA engineers to log the bugs?
  • What processes should tech writers follow in order to publish rapidly during the two-week cycles, especially when tech writers have several projects at once, all of which have two-week release cadences?
  • How can technical writers be valuable participants in the agile process when they are part of 3+ different teams, each of which has its own daily standups, sprint planning, and retrospective meetings?
  • Agile teams often follow a “fail quickly” approach that leads to coding in a lot of different directions in order to find something that works in the market. How can you avoid massive revisions of your documentation with each major direction during this highly volatile period of coding?
  • Agile teams often want to minimize the amount of documentation in order to stay agile and flexible (the principle is “working software over comprehensive documentation”). How do technical writers negotiate the de-valuation of documentation on agile teams (even if the docs mostly refer to project documentation instead of user documentation)? How does minimalism factor into agile practices?
  • What time management techniques can you implement to be more efficient in order to meet the fast-paced demands of agile teams? What can you ignore or cut out of your day? Are all meetings necessary to attend in order to convey the importance of your role on the team?

Share your experience

If you want to share your experiences with agile, you can do so in the comments on this post.

Other Stuff