I am a senior software engineer working in a department with two teams:

  • One team (model team) is responsible for the creation of forecasting models.
  • The other team (my team) is responsible for the implementation of these models.

Once I complete the implementation of the model, I send the model team the software, including an internal validation report explaining clearly what calculations are implemented.

The model team is now publishing my software along with the documentation explaining the forecasting model. This sign-off request is totally legitimate as I have the expertise to confirm that the implementation coincides with the documentation.

The tricky part comes at this stage:

  • The documentation is very badly written with many inconsistencies.
  • Since I am doing the review, they expect me to do all the work to rewrite the documentation and correct the inconsistencies.
  • Once I complete the review, they want 1-2 meetings to be sure that they understand the documentation correctly.

I don't find this situation acceptable. What is the best way to react to it?

My initial idea is to send back the documentation to the model team with a list of the biggest mistakes (with the boss in cc) and ask for an updated document before I start the review.

Are there other possible solutions?

  • 2
    I have a friend who did checking of tech docs and would just keep sending them back .... Along with things like « I have highlighted all the errors on the first page as an example, you need to work through the whole document ». The trouble is, if you have done it before then you have list already...
    – Solar Mike
    Mar 22, 2019 at 18:08

1 Answer 1


Go ahead and review the document, as you have stated that it is a legitimate request on their part, but do not re-write the document or correct anything in the document. Simply point out all of the problems with the document and give them the opportunity to fix them. Send them the document with your comments/critiques and unless you normally CC the boss when doing these reviews, I would advise against it.

  • 1
    This. "review" is not "edit". Point out the inconsistencies (broadly or narrowly, depending on how many there are), possibly suggest some places they could go or helpful technique for fixing them, and send it back. Their expectation does not write your task orders.
    – Ben Barden
    Mar 22, 2019 at 19:05

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .