Categories
blogging documentation writing

Rotate your stock

As a university student, I worked one summer as a line cook in a new-age tempura restaurant. The chef there was a grizzled US Navy veteran who went by Lodi. He spoke with a New Hampshire accent and worked his knife like a man gutting fish on a trawler coming ’round the Portsmouth Harbor Lighthouse.

My first day on the job, he showed me the walk-in refrigerator, a cold, damp, vault with shelves from floor to ceiling. He said:

Upper and lower shelves are for produce boxes fresh off the truck.  Shelves from your head to your waist are for food that’s ready-to-cook or ready-to-serve.

Always put a lid on your containers and always rotate your stock. Everything should have an expiration date. Toss out everything that’s expired. Cut off anything that’s spoiled. Sniff or eyeball everything and ask yourself if you’d eat it. If in doubt, toss it out.

Then, bring the good stuff forward to make space behind it. Before the lunch rush and any time you’ve got a minute to spare, cut vegetables and prepare food to fill these empty spaces.

It seems like common sense now, but as a young man, this system made a big impression on me.

I’m still doing it in my work today. I just finished a project where I inspected my team’s entire doc repository, tossed out the obsolete, refreshed the good, and moved it forward.

You can do this, too. For tech docs or blog posts:

  • Inspect your legacy content at regular intervals.
  • Remove what’s obsolete.
  • Refresh what’s good and bring it forward.
  • Fill your customers’ information needs with new content.
  • Take steps to make the process more systematic.

In tech docs, there are ways to make replacing content easier:

  • Keep a release-cycle checklist with a “remove obsolete content” task on it.
  • Write modular documentation.
  • Tag content that’s version-specific so you can search for it.
  • Use link checking software.
Categories
open source technical writing

Writing and publishing on GitHub

I hope to create an open community around documenting open-source software and practice what I preach: To eat my dog food, as they say. What better way than to create a repo and invite the contributions of other writers?

To be honest, its a bit tough to do this. I believe in “open source.” I promote it, even.

But here I am preparing to put my most ambitious project out there for others to join, and part of me is holding back. Inviting others to join challenges my sense of ownership. To put these feelings in words: Will this end up creating a mess of written-by-committee pablum that serves little purpose? As a writer, I like to revise and craft my work iteratively. How can I do that if I’m fending off the well-intentioned interference of other writers looking over my shoulder?

To overcome this hesitation, I have to re-envision my notions of ownership. Is this “my content?” Is this “my project?” Aside from contributing content, then, I hope to provide the system by which it gets created.

Systems are composed of people, processes, and technology.

This system I’m creating will consist of:

Categories
jobs learning technical writing

Do you need tech writing experience? Write for one of these open-source projects.

https://medium.com/@rolfedh/do-you-need-tech-writing-experience-write-for-one-of-these-open-source-projects-14aa84de827b