How to document a bad project without shaming anybody?

Question

I've taken part in a catastrophic freelancing project full of bad decisions. I left it. As part of the handover, I have to "document my work", which essentially means I have to document the whole project (I am the first who wrote any documents on it).

Now I have to explain how things are going, its structure, architecture, development workflows, etc. It is full of mistakes. Now that I am writing it, I am shocked and also surprised.

The professional behavior would be that I simply write the document without mentioning anything that I think about it. Now the problem is that my name will be in this document, and thus it will seem as if the bad decisions would be at least partially mine.

Of course I could explain, or at least indirectly mention, that "no it wasn't my decision". I could, but it would be obviously highly unprofessional.

I could also write the documents without mentioning anything about any responsibilities. The problem is, that it would in this case shame my name, too. I can also suspect, that my (ex-)coworkers would have a tendency to shame me, instead of acknowledging their mistakes. But I obviously can't shame also their name.

How to solve this contradiction? Or, in a more broad sense: what is the optimal, professional way in such a situation?

Answer 1

Your documentation should be 100% neutral. As you mentioned, you should not put any of your personal input into the documentation regarding how you feel about the project, people who worked on the project, design details, etc. If you kept a good paper trail or have the paper trail from the people who were on the project, you will be fine since it will be clear you were not the one making the poor decisions.

As for your new documentation, it can be done without mentioning anyone specific. For example, "Tom decided to denormalize the database tables in order to make the code easier to write, but in the end it became unmanageable and hard to work with" could be rewritten as "The decision made regarding data storage was to denormalize the database tables in order to reduce the amount of code needed to be written on the app side. However, the data became very hard to manage due to a lack of good relationships and structure among the data and tables". This allows you to still clearly communicate the issue and what happened without blaming.

The assigning blame comes when you provide emails, meeting minutes, and anything else to develop a paper trail of how decisions were made. Again, you remain neutral as the person who is doing the documentation, but you provide any relevant communication and let the reader come to the logical conclusion based on the content. If there is an email chain where you disagree with a decision or you weren't even part of a decision that ended up failing, anyone reading the email will understand it was not your fault.

Answer 2

Normally, you would say things like "I decided", "we decided", "our team leader decided". If you say "the decision was made to do X", or "it was decided to do X", especially if it becomes obvious that it was a bad decision, that says quite clearly that you don't want to mention names, and that you deny having contributed to this decision.

Answer 3

You are documenting the system as-is. You are not passing judgement on it or those who wrote it. Don't worry, if the documentation is clear enough, others will pass judgement for you.

If the app is properly stored in various, date stamped versions, it should be clear that your document was produced well after the system was "done". If the app is so big that it took several people to write it, then I don't see how this app could be pinned on you and you alone.

Do your job of documenting and forget the whole thing. One caveat: when you document, make sure that you don't use "I" or "we".