Challenges facing technical writing
Technical writer at Government Digital Service UK
Early 2014: GDS had many products with documentation but no tech writers. What does good government documentation look like? Shall they use automation tools like Swagger or Raml?
They were then still relying on their developers to write their documentation - but developers' priority is the product. Hired/hiring tech writers.
GDS follows the agile principles but they face challenges: the focus is on the product not the docs.
Challenge #1 is the approach that the product should be so good it should speak for itself, so we need no documentation. To promote docs, show user research that users do struggle and need documentation. Sometimes it's hard to translate user reseach data into a prioritized to-do list.
Challenge #2: the docs writers are only brought in when the product is ready. They loose data from middle of the developement process.
Solving these challenges by:
a/In different groups their tech writers integrate differently
PAAS, Ben: treat the docs as developer stories, end-of-week email to update on docs changes.
Registers, Jen: not part of the dev cycle, watches out for pieces of work that might impact the docs.
Verify and Notify, Cathrine: developer makes the docs changes and tech writer reviews the pull request.
Documentation is not part of definition of done in GDS. Open for opinions on that.
b/ Creating standards to assure users that the product is up-to-date, coming from a trusted resource and is accurate.
User research to create a template to target different users' information needs.
Documentation prototype format for developers within the government.
Keen to learn about how to make GDS content more agile.