In episode 91 of The Content Strategy Experts podcast, Gretyl Kinsey and Simon Bate continue their discussion about using text strings and microcontent. This is part two of a two-part podcast.
“Make sure that their voice is heard. All groups that are using your strings need to have some input or have a way of communicating their needs to the organizations controlling those strings.”
– Simon Bate
Gretyl Kinsey: Welcome to The Content Strategy Experts podcast, brought to you by Scriptorium. Since 1997, Scriptorium has helped companies manage, structure, organize, and distribute content in an efficient way. In this episode, we continue our discussion around text strings and microcontent. This is part two of a two-part podcast.
GK: So then, yeah, we talked about all the considerations for content creation. What about content maintenance?
Simon Bate: Well, of course, in content maintenance, again, we get back to the same metadata that I keep harping on, and that is that having strings, having descriptions of the strings, help people perform maintenance tasks. So again, you may have particular reasons for saying things in a particular way, and it’s always good to pass along that knowledge. And not just as folklore within your company, but actually, is there something written down, and the closer to the thing that it’s describing the better. So if you’ve actually got a piece of metadata along with your string that says, “These are the considerations that we need to use when working on this string,” then that’s a good thing to do.
SB: Here’s another translation issue, and this is more a maintenance thing with translation. And that is, when you’re sending something off to translation, particularly when it’s individual strings that are just sort of individual pieces of information in isolation, you need to pass along information to the translators that say, “This is where this is going to get used.”
SB: And again, this gets back to what I was saying earlier, when you have a string in isolation, a word in isolation, like the word file, it could mean it could be a noun, or it could be a verb. The translator needs to know that piece of information.
SB: Along with maintenance comes sort of a management aspect to it. And that is, it’s always a good idea to identify a responsible individual or a group that is responsible for overseeing things, like the aging of content. At some point, somebody has got to go through all these strings and say, “Oh, this one’s no longer used. This is no longer necessary, and remove them from the database.” Also, what you’ll find, this is a classic reuse issue, is if you have a string and it’s reused in a number of devices, and then one device changes slightly which renders a string ambiguous or not meaningful anymore, you may need to decide, okay, it’s time to create a new version, a separate version of this string for use in this case. And so it’s always good to have some group to oversee or control how often strings get modified or how often they get forked into separate strings for separate uses.
GK: Yeah, absolutely. And having that kind of an individual or a small team in charge of that is especially important if you have multiple departments, or maybe even every content-producing department across the entire organization all coordinating and working together. You might have everybody in one repository or in separate, but connected, repositories and they’re all collaborating on the content, and they all need to make sure that there is kind of that one person or one group in charge that can make sure that one department isn’t just kind of going off the rails somewhere and making decisions that could affect all the rest.
SB: Yeah. And also, at the same time, it’s really good to make sure that people don’t feel left out of the process. So you also need to make sure that their voice is heard, for all groups that are using your strings, that they all have some input or have a way of communicating their needs to the organizations controlling those strings.
GK: Yeah. And I think this really gets back to what we talked about way earlier in the beginning, about how a lot of people, when they’re in the planning stage, they might start with that spreadsheet. And I think if that originated out of one department, it’s really important to make sure that any other groups who are going to be involved in the content are all aware of what’s in there. They maybe get a chance to come in and add their own ideas or their own requirements to that spreadsheet. Or if they’ve got a spreadsheet of their own, that it all gets consolidated. And that’s probably one of the best times in your project to choose who this responsible individual or group is going to be. And then that way they can take it smoothly or as smoothly as possible. It’s never perfectly smooth, but they can take it as smoothly as possible from that planning stage in something like a spreadsheet into your actual DITA environment.
SB: Yeah, that’s right.
GK: So now let’s talk about that third piece, which is content delivery. So what are some of the implications on the delivery end for microcontent and strings?
SB: Of course, the main idea about delivery is, you’ve got these strings and they’re in your repository in some form, and they have to be then output in a form that can be consumed by the device with the software that’s going to be using those strings. And of course, if you’re maintaining your content in DITA, good thing is, you can then use the DITA open toolkit to transform your strings in your CCMS into some delivery format. And the typical delivery formats that we see, there’s just plain text we’ve seen. Sometimes, there’s the need for comma separated values. But then also JSON is, nowadays, a very common format for encoding information. Many devices are set up to consume it.
SB: So of course, when you’re creating your output format, the software or the device that consumes those strings is going to have very specific expectations of those strings. It’s going to have expectations of the format of the strings, and expectations about the tagging. So how are each of those individual strings identified? In some cases, you don’t have much say over that. Sometimes the hardware department’s usually months ahead of you in terms of development and things, and by the time you deliver, everything’s on silicone and there’s nothing you can do. If you’re lucky, you can start early enough and start to negotiate, start to discuss with the hardware team, what might be necessary for supporting these strings. Are there things they haven’t thought about? And so then you can actually get some… Dialogue can occur between your groups about what they expect and what you can deliver.
GK: Yeah. And I think we’ve seen a few examples of this just in the way that some companies organize their departments. In a lot of cases, there’s a separate content department that does all of your technical documentation. Maybe there’s another one for your marketing, another one for your training. But we’ve also seen a few companies that do something more like, there’s each department for maybe a product line, and then they have their own, a writer or two, who kind of reports to that group or is ingrained there. And that’s really showing that that company values their content and is willing to kind of have that conversation earlier in the game. And I think that, even if you do have more of that sort of traditional structure where you have a content department, it’s still important to have people from that department going out and talking to your product developers, to your hardware team, and just coordinating earlier rather than kind of shoehorning either group into something.
SB: Yeah, absolutely. Communication among groups is essential.
SB: It’s essential for good product delivery.
GK: So what are some other considerations around JSON?
SB: Now, these are some considerations for JSON, but they may be applicable to other output formats. This is probably built in by the people consuming the JSON. But you do need to figure out, in JSON, a way of passing the JSON markup characters in your strings, and particularly the quote signs. So you have to have some way of encoding a quote. Then when they receive the quote, the quote sign, they can decode it.
SB: Now, the reason I call that out is, within JSON the quotation mark, double quotes, is used to delimit a string. So we have an open quote, close quote, but if you should actually need to use a quote in the middle of that string, you’ve got to do something so it’s not interpreted by JSON as being part of the JSON itself. That’s a syntax violation. Quotes need to be encoded, but also, it’s good to do the same thing for other JSON markup that may occur within your strings. For instance, square braces, curly braces, and semi-colon are also characters that are very important to the JSON syntax, and probably should be encoded.
SB: Another thing really worth considering is that strings in JSON, once you say, “Oh, this is a string,” that’s just all it is. It’s just a sequence of characters. And so if you’re thinking about something like DITA markup, within a DITA paragraph, you start a block object, a paragraph, and you can write characters, and then you can drop in, inline, DITA markup that does things to the characters. Like you could say, “Change to bold,” “Change to italic.” There’s a number of other things you can do for markup within a particular paragraph.
SB: If you take that paragraph and move it to JSON, all you’re going to have is the series of the characters in that paragraph with no markup, because there’s nothing within JSON for an individual string to have inline markup.
SB: Now, there are a couple of ways of dealing with it. And one is actually to have very complex JSON, but have the JSON understand that it’ll output individual objects for each piece of text in each individual format. So you might have an object that is just regular text, followed by an object which is italicized text, followed by another object which is normal text.
SB: Another way of dealing with this, and again, it’s based on the consuming system, if it can deal with this, you can actually drop something, an encoded form of markup, within your strings. So you might use a whole separate character set other than the JSON characters to say, okay, here’s regular text and here’s where italic text would start. And then here’s where italic text gets turned off again, and so on. But again, a lot of this is based on the consuming system. A lot of this gets back to our previous discussion about, you’ve got to be talking with the people designing the devices or consuming the content, and they have to know that inline text may be an issue, or they may say, “No, we’re not going to deal with inline text at all.”
SB: One final thing about just generally generating output, and this gets to all levels of things, and we see this a lot. And so it’s always good to sing it out. If the particular form of output needs to be in a different case, say all uppercase, or InitCap, or something like that, your sources don’t have to be in all uppercase, because that kind of character change can always be done by your output formatter. So as you’re transforming it in the DITA open toolkit, you can just say, “Oh, output this string, and while you’re outputting it, change the case to uppercase.” So it’s always good when your sources keep to minimum change of case within those sources.
GK: So now that we have talked through, we started off with content creation, went into maintenance, and wrapped up with delivery, I think one really good way to kind of tie all of this together is to talk about project management expectations. And we already touched on it a little bit. We talked about content governance and having that small team or an individual to sort of oversee everything, but what are some project management expectations that people need to keep in mind when it comes to working with text strings or microcontent?
SB: The main one, and it gets to sort of business common sense, you may have very high expectations about what you can do, the people who are taking in the content and they have high expectations about what they can do, but there may need to be, at some point, a middle road. There may need to be some compromise, a compromise of, what is the best you can do versus what is it that the device is capable of doing, or what is it that we are capable of delivering?
SB: So there has to be a compromise.
GK: And I think a lot of what informs that compromise is cost and time. So you might have the technical capability of doing something, but if you don’t have the budget for it, if it doesn’t make financial sense, or if it’s going to really conflict with some of the time constraints you have, some of your deadlines, then it might be something to kind of consider for the future and slowly roll that out. But that’s one of those things where you can’t just have everything and you do have to make those compromises.
SB: Yeah, yeah. In my role of programmer, I often think, “Well, everything is possible. The question is, is there money to do it?” So I think the other thing to keep in mind with project management is that having strings, short text strings, microcontent, you can do a lot, it’s a good way of maintaining things, but it can’t necessarily solve all the issues that you may have. There may be need to go to other ways, like full-text strings, or other considerations for how you encode or transform this information.
GK: Yeah, absolutely. And I think that really is a consideration, not even just for strings or micro content, but for everything that… There’s no sort of one size fits all way to solve all of your problems. So it really does get back to what we talked about in the beginning, about planning your strategy and sort of figuring out how does the use of microcontent fit into your larger solution.
GK: Well, thank you so much, Simon.
GK: And thank you for listening to The Content Strategy Experts podcast brought to you by Scriptorium. For more information, visit scriptorium.com, or check the show notes for relevant links.