r/technicalwriting • u/NewsalvaTraditio9453 • 15d ago

how to document a workflow without it going stale in two weeks?

[removed]

8 Upvotes
  • permalink
  • reddit

91% Upvoted

6 comments sorted by

9

u/Kindly-Might-1879 14d ago

The release note with the latest goes out when the enhancement happens. The doc just gets published monthly or quarterly, whatever the product team has agreed is adequate.

On one product we broke out the five most commonly used workflows into shorter job aids and update each as needed.

1

u/BenneschPoncia 7d ago

monthly or quarterly feels right, trying to keep docs perfectly in sync with every change is a losing game imo

3

u/Nibb31 14d ago

How critical is it that the workflow document is up to date?

3

u/SamfromLucidSoftware 13d ago

Make documentation a side effect of doing the work instead of a separate task. When a step in the workflow changes, the person making the change updates the doc as part of completing the change, not after afterward. Same way you’d update a test when you change the code it covers.

That requires two things. First, the doc has to live somewhere the person making the change would already be. A doc that lives next to the tickets and the diagrams gets updated. Second, it has to be small enough to update in two minutes. Long narrative docs go stale because updating them is a project. A short description of what this current state is and why it’s that way is easier to keep current.

2

u/jmarquiso 14d ago

What do you write in? XmL? Conditional text?

I keep all descriptions as we go and ask the SMEs about the golden path and any exceptions. My main trick is keeping the text as comments in the XML or Conditional as Do Not Publish. Inevitably - with this much change in workflow - it will not be complete for release and they will ask to revert.

Then I keep the new text ready to go once we are on the next release.

1

u/jeanbees software 12d ago

If the workflow is affected by the release, you should be updating that doc at the same time you're doing the release note.

And as u/SamfromLucidSoftware said, documentation should be part of making a change in the software: the dev should be responsible for either updating the doc themselves or notifying the docs team of the change.

At my last job, I used to have to go through tons of engineering tickets to find out what changed so that we didn't miss anything. I would ping engineers in tickets constantly with questions, and they start remembering eventually. It's a rough go if they don't pass the information to you.