From dev to content – there and back again

Part of the evolution to Documentation 4.0 so that information around software caters for the proper needs is designing a journey from the outset. Part of that journey is the road from development to content and cycling back to ensure that both improve each other.

An image I like by Alex Yakyma – https://www.linkedin.com/in/ayakima

There are two other elements that are key to understanding this article. First of all, the era of big doc is over for technical writing, and second, agile methods and especially stories can contribute to what we used to call documentation.

What does dev and content have in common?

The users

They have the users in common first of all. Software developers work for end users in the long run and so do content developers (ex technical writers). Does this mean they seem them in the same way? Have a look at some humour to help understand : As a software developer, this is how we view ALL end users.

Do developers think the users usually get it wrong or ask for stupid stuff? Do content writers take user differentiation into account? A lot of this comes from barriers or distance from the end users.

The key issue is how they agree on a perception of users. For us this is done through sharing the persona analysis of the user base: see Personas as a means for mapping user experience for information delivery. Although this article is written for content delivery the same notions can apply for developers.

The objectives?

Traditionally developers and content developers do not share the same objectives especially not short term. If agile methods apply to both, then yes, the objectives can be aligned. Releases of software have to contain content for users in the future. That an overall objective. Going down a level and looking at scrum objectives, there is area for coordinating better to improve the user experience.

The methods?

We prone agile methods. If developers and content developers use the same methods, then they understand each others process better. They can even cater for each others needs. Release plans can incorporate content developers and get them up and running earlier. Collaboration can help improve the UI and reduce a need for content.

The product owner?

For us, the product owner role is key to having products move forward since he translates ambitions into practice.In this respect, development and content development should share the same product owner.

How can devs and writers share?

They share the same basic information on what the software is designed to do and what niche it occupies. That’s not what this part is about.

There are a lot of instances where they can share when user requirements are correctly addressed in agile methods:

  • briefs on release plans.
  • scrum reviews.
  • story definition.

Story definition is the hard one. There is a lot of room for improvement in writing stories in agile methods and we’ll deal with this later.

So it’s about sharing through tools and spending time face to face. Development scrums can include tasks, even stories,  for content developers. Content development scrums can include tasks for developers, especially on terminology and UI.

Collaboration in release plans

This means planning a release which includes content delivery and not just the development. Often the need for content changes depending on what was developed and how. The earlier the user content is built into the process, the earlier some options can be better tuned for use. If a content developer has to spend too much time on content for an option, maybe something is wrong with the design, and we’re all better off knowing this earlier.

Content can be built at this phases easily – howtos and procedures are built around the release. FAQs are what the content developers often ask developers.

UI and UE with content developers (writers) involved?

Often, content developers are the first testers. In the methods we prone, they are aware of user persona and requirements. In this case, they are helpful in overall ergonomics, process and UI layout. They also have a role to play in terminology, the semantics. They are the ones who should write the tooltips as part of the content. Typically this collaboration in down at the scrum level.

Stories as content candidates

Can stories that are written for development be content candidates? We say yes. Obviously not all of them, not the technical ones for instance. But any stories written with the user in mind has to be written so that that it can be promoted as users content later or at least connected to a content production cycle.

This means a little more effort on writing stories obviously. It might even involve getting content developers onboard here, especially if the have experience with the users. Support does, so do content developers. For most developers this will be hard to integrate, but it’s about breaking down barriers are removing isolation. Agile methods contribute to protecting development teams. That’s alright, but in some cases, we need to stop over-isolation.

As far as stories related to usage are concerned, content developers will need to understand them. It’s about time to look are style guides for writing them and to do that there is no one better capable that a content developer.

Test cases are often content candidates for user-oriented information.

Then what wee need is the technology to deal with this.

Can developers write?

Generally, they can and they should. Part of what they write is the development documentation. This is for internal use of course, so we’re less strict on style, concision and all the other elements content development deal with.

Now, what if the tools for dev doc were compatible, even the same? This is one direction we need to move forward on.

In this context, developers can contribute to the first content candidates.

Can content developers test the UI and contribute to ergonomics?

They do and have for a long time. There are often the first ones to have to deal with it. Integrating their feedback into scrum methods is essential.

Obviously, to test, they have to be integrated with the product strategy and release vision and also know something about user requirements. If the writing process is disconnected or off-line, they have to build this anyway.

Content development is more and more oriented toward users experience and satisfaction; this is why they have a role in scrums to test the UI.

Co-testing

The end of a scrum or at least the release plan have a test phase integrated. Content production should be organised so that at least the first level or round of content is available for testing also. Getting content wrong can mean the development is also unclear. Testing ergonomics can mean reducing content.

In some projects, the content also contributes to test cases.

Synchronised delivery

This is the end game and the chief motivated for collaboration between two different fields around the software. It can be achieved.

Content doesn’t have to be perfect for a first release, it just has to be. It continues long after the release is over and the product is handed over to support. If you’re serious about a satisfied user experience then this is one way to go about.

Software isn’t just about technology, it’s also about satisfied users.