[BossingAround]

Some times, the writers don't want to repeat themselves because they were taught that it's "poor writing." And I'd agree, maybe, in (some) prose.

But in tech docs, please, repeat yourself instead of using "this", "that", "those", etc., even when perfectly non-ambiguous.

This should be preferred "The service is now ready. To check the service's status, ..." over this "The service is now ready. To check its status, ..."

[KineticLensman]

> the writers don't want to repeat themselves because they were taught that it's "poor writing."

Yes! As you say, it massively depends on whether you are writing fiction or non-fiction. In any sort of formal document, especially technical reports, etc, the reader should never have to spend time working out what the author means. I used to be a doc reviewer in a previous life, and lost count of the number of times docs used different terms to mean the same thing, especially where multiple authors were involved, or a single author was writing different sections at different times.

General plea: If you value your readers, please, please get someone else to check a doc to look for these sorts of problems. If multiple authors are involved, always get someone on the team (a lead author?) to do this check even before submitting it for formal review.

[esquivalience]

I found your last paragraph entirely unambiguous at all three levels, which led me to disgree with your overall point. Before that I was with you!

[langcss]

The benefit of "The service is now ready. To check the service's status, ..."

Is when someone needs to amend this sentence later, e.g. inserting another point:

"The service is now ready. This means you can query the health endpoint. To check the service's status, ..."

It makes the writing less likely to become ambiguous.

Most documents I see in work will constantly have sentences added/removed as things change.

[karmakaze]

Many 'rules' including this one can be broken if you know the tradeoffs and can make the case-by-case choices correctly. But that was a poor example for motivating a behaviour.

[andirk]

We should write with *pointers.