1

What is a good way to mix non-dev content, like FAQ text or internationalization text, into a development pipeline?

For example, suppose you have an app that is being coded by software engineers, but it provides a lot of text to the user and that text is authored by non-engineers. The text could be a FAQ that is written by documenters or labels that might need to be translated or all sorts of constantly extended and modified text for the app.

The current/naive pipeline is for these authors to write their text, send it by email or extracted from a document store, the developer would cut and paste the text into a string or strings in the code.

This is great because everything is code: managed by VC, change management, etc etc etc. All artifacts are in the hands of SW development. The non-devs won't have to learn VC or programming to make a change, they just pass it over to the devs.

Except... This is a extra painful step. Both the writers and the devs have to make a change to their 'domain'.

The writers of the text should be in charge of their own system, handling of versions, how to work on things. A little bug (a typo or poorly chosen word) should be handled by them; if it goes through devs, the edit and release is painful.

One way to slightly ease this pain is to simply refer to a file in code and then simply overwrite the file with a new one. It still needs a step where a dev has to modify the repo but at least it is not editing a file, just replacing it (similar to the situation where a designer creates some images and their artifacts are just dropped in as files).

But what if the writers are constantly creating new text. Even that 'file drop in' is still an extra step.

Is there an established and/or easy way to let writers edit their files and have them automagically part of the build? Either the only communication from writers to SW builders is 'please rebuild', or the text itself can be deployed independently (as long as the code is compatible with the file format).

To make this more concrete, I have a set of files in Google Docs that contain text that is to be part of a React Native phone app, and I'd like the writers to have a parallel 'continuous' development process to the software engineers. I'd prefer not to have the writers both blocking software development (the writers content has to be completed for SW to build and deploy). It's OK to me that the writers may have their own VC (Google Docs does that very transparently for non-sevs).

8
  • 1
    Related: Content management system
    – John Wu
    Sep 7 at 22:04
  • 2
    "It still needs a step where a dev has to modify the repo but at least it is not editing a file" You don't need to be a developer to copy and paste a file.
    – Flater
    Sep 8 at 11:11
  • 1
    @Flater: in an environment where only devs have write access to git repos, you need one.
    – Doc Brown
    Sep 8 at 11:28
  • 2
    @DocBrown: If you make your devs the sole point of contact for accessing the source, then the question on how to have non-devs contribute to the source is moot. The only challenge here is one of access, which is a self-imposed hurdle.
    – Flater
    Sep 8 at 11:33
  • 1
    @Mitch: Git (or any VCS) is just a storage system, and not inherently tied to software development on a technical level. I've seen teams of writers use Git for a collaborative writing project. It might be easier to just let these non-devs use the same system that your devs are already using, as opposed to having two separate systems, having to wire them together, and then come up with some custom way of doing explicit versioning to marry up the right version of content from both systems.
    – Flater
    Sep 9 at 7:47
2

At the end of the day, someone has to make a deliberate a decision which version of a certain document or artifact shall be merged into which branches or releases of your software - even when there was just a typo fixed.

The technically most simple solution would be to get the writers to use the same VCS as the developers, so they can simply make pull request. However, this might be too painful for them, especially when they not just create and deliver text files, but binary files.

Hence, if writers prefer to use a different system like "Google docs", you will need to automate the process of grabbing and integrating a certain file version from there. This Q&A from webapps.SE gives some hints how this can be accomplished using the Google docs API. So the whole process of getting a new version of a doc file may only require to enter a new version number into a "transfer script" and run that script, which queries the API of the writers "document storage system", downloads the file(s) and does some further processing to merge the content into your software.

Regardless which technical solution you use, you first have to make sure the writers are versioning their artifacts in strict fashion.

2
  • Not only would git be too painful for them (and for the devs or devops people who would have to train them, and fix things when the non-devs break things), the difficulty would lead the non-devs to not want to use it at all... the idea is to have the non-devs do things as frictionless as possible with tools they are used to.
    – Mitch
    Sep 8 at 22:01
  • The googledocs api looks like it would allow coordinating its versions with git... that might be the solution.
    – Mitch
    Sep 9 at 1:00
1

To make this more concrete, I have a set of files in Google Docs that contain text that is to be part of a React Native phone app, and I'd like the writers to have a parallel 'continuous' development process to the software engineers. I'd prefer not to have the writers both blocking software development (the writers content has to be completed for SW to build and deploy).

So I think in order to plan this you need to think about how the text is coupled to the app. What happens if the app needs a particular piece of text and it hasn't been written? Conversely, can a new piece of text be deployed without adding code?

How is bugfixing to be handled in the text? How is a "release version" to be identified?

labels that might need to be translated

There are various "internationalization" or "i18n" workflows, but what usually happens is:

  • all the text to be internationalized is identified within the product and transferred to a "resource" file, where it can be looked up by integer ID
  • a tool spits out a big list of all the English resources to a spreadsheet
  • a translator sends back the spreadsheet with an extra column for the text in the target language
  • a tool creates a different "resource" file for the target language
  • the target language resource file is selected at runtime
3
  • OK great, good suggestion... a specialized workflow just for i18n would work for that use case. Now I have to think of other use cases where the text produced isn't translated but often modified and increasing, like daily messages.
    – Mitch
    Sep 8 at 13:49
  • "Daily messages" sounds more like "content" in a CMS, so I guess you need to provide a bit of app backend for entering the content into a database of some kind, or filesystem of the server?
    – pjc50
    Sep 9 at 9:02
  • A CMS sounds like the way to go but it feels particularly directed at coordinating large numbers of artifacts for static websites, and somewhat of a heavy technical lift to connect to a little react native app instead of a big website.
    – Mitch
    Sep 9 at 12:50

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.