Handing over, documentation

jcbellido June 10, 2018 [Code and Chlorine] #Programming

During the last weeks I've got the request to write some documentation of the localization tech stack I've been working during the last 18-ish months. In the team I'm working with nowadays, there's a group of specialized documentation writers. Tech writers.

And when you check the docs they create, it's clear they're professional. Unified styles, neutral English, linked documents, different sorts of media including images, gifs, videos, links to code, examples in the game ... everything you can imagine. It looks and it is costly.

And that works well for teams of some size. Let's say sizes over one person. I've been driving aboslutely every aspect of the stack by myself: DBs / Caching / Services / UI / Exchange formats. On two very different projects at the same time. Starting from scratch. It's been a blast. But it's a messy blast.

How it should look, for me

When consuming documentation I want 2 sources of information:

  1. As a final user of the stack. What does the user see? How does the UI work? Which are the metaphores deployed?
  2. High level architectural view of the code base. Server based? Service based? Local user only?

... and, once what the intent is clear and the language with the user base is defined, then, if possible, show me some unit cases. Nothing fancy or spectacular something to start tweaking here and there.

That would be the gold standard.

Then, obviously it's better when the code is not rotten. But that's a daily fight. And a different discussion.

So what's next?

Umh, after the E3 mayhem, maybe I'll be able to convince some producer to redirect the work of some peers at QA to work with me for a couple weeks, and we'll go together through all the insane nooks and crannies that one-man-operations tend to generate at these scales. If I'm lucky this person will be able to create some end user documentation and we'll discover some easy points for improvement.

Meanwhile, obviously, I have even more stuff to develop, including a nasty data migration, related with a deep change in our domain.

Oh, the good olĀ“times when I believed that running Doxygen and flee was enough.