Requirements that you didn’t know were there (Write the Docs Europe 2017)

Proudly presenting the slides from my talk at Write the Docs Europe 2017, now on SlideShare!

Plus, fresh recording of the live talk.

For those of you who missed it, here’s a short intro.

Every doc that you deliver is as useful as the requirements it satisfies. Typical requirements revolve around target audience, method of delivery, technical limitations. But after the doc is done, then come unexpected expectations. John – your key stakeholder – dislikes clichés like corporate templates and wants to stand out with neat Apple-styled docs. Also, it was a mistake to tell him about similar ‘really cool docs’ you already did for his colleague Jane because apparently they don’t get along well, and now he proudly decided that he won’t mimic her decisions… Suddenly, your docs should not only make users happy, but also help your stakeholders achieve their aims – move up a career ladder, impress the manager, get a bigger paycheck. The success of your docs depends on requirements that you are never told but are still expected to meet. This presentation is about reading your stakeholders and deducing the ultimate requirements.


Effectiveness as a habit

The 7 Habits of Highly Effective People by Stephen Covey. Book Review.

In the last decades, motivation literature has flourished to an unprecedented extent. This is a cultural phenomenon that cannot be missed: people have become interested in self-development, constant improvement, and success. “Ah, yes, success…”— you may sneer skeptically just as I did when I first saw the name of the book. Yet, behind the mainstream title, I found deep thoughts that are applicable in my life journey.

Continue reading

Buzzfeed test: your ideal SME

In her recent post, Natalia Bortkevych very astutely described the typical cases of SME interviews gone wrong.

In truth, when the subject is confusing enough in itself, it helps little to have an SME who has aversion to human race or talks in the “codish” variety of English.

Still, even if your SME is able in every way – approachable, knowledgeable, adorable – it’s no guarantee they will be willing to grant you an interview or a review if they are busy, even if you sorely need it. On the other hand, if you are disposed pleasantly towards each other and get along well, they’re bound to be more cooperative.

And while there are many tips and techniques for building that connection with your SME, sometimes it just happens naturally. It’s much like falling in love – you just have to find the right person.

We have designed this test to help you find out what kind of SME is your natural match!


interviewing SME

Interviewing SMEs: Prepare, Talk, and Troubleshoot

Interviewing subject matter experts (SMEs) is one of the key soft skills that an Information Developer should possess. Our job is to get the technical input and turn it into a clear and usable output: decide on what is crucial and what is irrelevant, structure the information, and illustrate it with examples or graphics. Still, the much-needed input resides in the minds of the SMEs, and we need to act wisely to retrieve it—in other words, to master the art of interviewing.

Continue reading

Where do the technical writers fit?

There are times in our, InfoDevs’, lives, when we try to find our own place under the sun, I mean, within the team. We start questioning ourselves: “What should I do first? Is there anything else I can do? How can I help my teammates?” And our answer to the last question sets the role we play among the Developers, BAs, QAs, Designers, and PM. Are we merely doc writers defined by our proficiency in languages? Or are we an important part of the team that brings value and facilitates the work of each team member?

On the corporate level, the questions remain the same. The article by Sarah Maddox and the feedback for it by Larry Kuntz reminded me of the road towards self-identification that my fellow InfoDevs and I have taken.

How the story goes

We began as a Documentation Stream within the Software Engineering office, and over a year, after long debates of how we could be most productive—as a separate entity or as part of other offices like Marketing or UX, we formed the Information Development office, a full-fledged department in the company structure. That decision led to the common understanding that we could provide our services not only to the company’s external customers but also to the company itself. We help other offices as we handle corporate documentation of all types and formats. We deal with reviews and translations, prepare case studies and proposals, decipher pencil-written notes and turn them into cool infographics. That makes us recognizable among colleagues and shapes the image of an Information Developer as a competent and versatile professional. Also, being a separate functional unit allowed us to create the Information Development center of expertise where we share our knowledge and help newcomers grow.

Here we stand

This is how it works for our company now, and this story is in the making. Of course, the future might hold new challenges for us and new discoveries as our industry progresses, and you can never be sure where you might end up.

I’m sharing this article with you, so that if you faced a similar problem or still try to find a place within your company, this might set a direction for you.

Source: Where do the technical writers fit?

Use cases and technical documentation

What use cases are

A use case describes a sequence of interactions between a system and an external actor that results in the actor being able to achieve some outcome of value (Karl Wiegers and Joy Beatty “Software Requirements”, third edition, August 2015).

Technically, these are requirements specifications resulted from a thorough analysis and a number of discussion iterations with Product Owner and the development team (software architects, most probably).

Use cases give all parties (Product Owner, development team, as well as technical communicator) a clear overview of what functionality and interaction types between actors and a system will be implemented. The textual description of such interactions provides a precise picture for a Product Owner and other stakeholders that shows what their solution will be in line for and how exactly it will be happening.

Within the roles performed in the team that is involved in development and delivery of a software product, designing and writing use cases is the task of a a requirements specialist.

And you, an information developer, should understand the true worth and value of use cases on a project and try utilize them to the fullest extent.

Continue reading

Technical Accuracy: Who Does the Testing?

Technical documentation is an integral part of a software product and must be regarded as such. We all know what happens after a software feature has been developed: it goes through a code review, and then it is thoroughly tested by a QA team. Before each release, the entire application undergoes multiple tests.

Technical documentation goes through a similar process: with each update, it passes several rounds of reviews. However, what about testing software documentation as a finished product? Among various roles in a project team, who is responsible for doing that?

Continue reading