I work in software, with very, very complex systems that are subject to quite a bit of risk management and process control. The company has a team whose sole purpose is to audit projects and ensure that all development teams deliver the required documents/artifacts, pass through all the milestones in the proper order, etc., before taking a project live.

Recently I was given the task to create a design document, which is required by the official process. In theory the document is written before the development work is performed so that all the programmers are doing the right thing. However, we recently switched to an Agile process which is very light on the documentation. So all the development work has already been completed, based mostly off of tasks stored in our TFS system. The document is being created retroactively just to satisfy the audit. Nobody will ever actually use this document.

Aside from the simple fact that this is busywork, it also seems like it is intended to fool the auditors into thinking we followed a process that we didn't actually follow. I believe the correct remediation would be to go back to the auditing folks and re-negotiate the way the process is defined, but management doesn't want to do that. They just want to write a dummy document to make the problem go away. I was literally told to insert just enough text and diagrams to convince a layman that the document was authentic.

Are there any ethical problems with this approach? Am I committing an unethical act by writing the document at my manager's direction? Should I escalate this over my manager's head?

  • The difference between your team and all the other software development teams is that you know you are not following the design document. Outright fabrication is unethical but compiling the TFS tasks into a document may be closer to the spirit of the requirement than what many other teams are doing. Is it ethical? I'll let others advise. – Ben Mz Jun 5 '18 at 1:48
  • 9
    You surely know the answer. Don't ask us if it's ethical, rephrase your question to what you are really asking. – Mawg says reinstate Monica Jun 5 '18 at 6:27
  • 4
    Don't you think the audit team may find the design document useful just to get their bearings? The real ethical dilemma will come if you're forced to include things such as backdates and "Approved by" statements. – Stephan Branczyk Jun 5 '18 at 8:54
  • everybody knows that during formal audits there are questions never asked (eg: is this a real/actual/used document?). which kind of audit you're talking about? formal? required by law? at will certification? as it is, your question requires to express a personal opinion. – Paolo Jun 5 '18 at 12:14
  • 3
    Depends. If the document contains the actual creation date that's a different situation than one where a false date is added to make it look like it was created earlier in the process. – Laconic Droid Jun 5 '18 at 12:46

I would say it depends on the type of the document.

If it is a kind of document that is required before starting the project process wise (for example authorization requests that need to be signed by higher-ups), then it is closer to being a fraud.

On the other hand, if it is for example an architecture document, that describes the actual software that was delivered then it is fine, since in agile development, the architecture can change substantially during the development process.

In waterfall usually the architecture or interface description documents predate the time of the software development, but in agile development it is very common that these are live documents, or documents that are created upon request, or at the time of the final delivery.

| improve this answer | |
  • 1
    Agree with this, and it's to fulfill internal requirements anyway not defraud anything. – Kilisi Jun 5 '18 at 13:29

it also seems like it is intended to fool the auditors into thinking we followed a process that we didn't actually follow.

Are there any ethical problems with this approach?


Intentionally intending to deceive auditors is clearly unethical. In some cases, it may also be illegal.

Am I committing an unethical act by writing the document at my manager's direction?

That may depend on your personal ethics. Some would argue that you are only following orders. Others would argue that following orders that you know to be unethical makes your actions unethical as well.

Should I escalate this over my manager's head?

Practically speaking, this is a tough decision that only you can make. Consider:

  • do the folks over your manager's head already know?
  • do the folks over your manager's head agree with what the manager did?
  • are you willing to risk your job by going over your manager's head?
| improve this answer | |
  • 1
    I don't think the Nuremberg Defense would work in this case unless he is in the military. – solarflare Jun 5 '18 at 2:08
  • 1
    if the possiblity of breaking the law may exists, OP might also consult HR about this. – Walfrat Jun 5 '18 at 9:05

I think that you are missing the big picture here, you are focused on creating the documents, when in fact you should be looking at the process as a whole.

If the project/development team instituted a new process and/or development cycle (Agile) that has not been approved and sanctioned by the audit committee and established company requirements then your team is bypassing all of the guidelines, expertise, and internal quality control that were put in place to protect the company, its intellectual property, and reputation.

Ultimately the documentation is not the issue, it's the skirting and total disregard for the very mechanism put in place to protect you and your employer.

| improve this answer | |

I would like to point to this question on the Software Engineering Stack exchange: Can creating a Software Design Document after development be justified?

You should ask your manager for clarification on the SDD; it may be used in the future when other engineers maintain the project that you may not be aware of. As to answer your questions in this light:

Are there any ethical problems with this approach?

As Joe Strazzere said: Yes, if you are creating the SDD only to satisfy the auditors

Am I committing an unethical act by writing the document at my manager's direction?

Depends on the motivation of writing the document. I would clarify it with your manager.

Should I escalate this over my manager's head?

No, doing so without knowing the actual reason for retroactively writing the SDD may cause a bigger issue - you're complaining about a problem that may not exist.

| improve this answer | |

I'm assuming here that this is a purely internal process and audit (as opposed to being something that is required by regulation, law, or certification such as ISO9001) and that being the case I'd consider this to be just another box-ticking bureaucracy workaround rather than being out and out unethical. Realistically who is being harmed by doing this? Assuming the retroactive design document is accurate then only the timing of when it was done is being fudged.

In larger organisations (and the fact that you have a dedicated team for process auditing suggests you aren't a small organisation) these sort of flawed "official" processes occur all the time and essentially harmless workarounds like this happen. And often these workarounds benefit not just those using them but the organisation as well. For example it's quite common in many iT environments to require a ticket to be raised before any work can be done, so when a support tech is walking past someone who has a simple issue - say the video cable has come unplugged from their monitor. The tech should (according to the process) tell the user to just raise a ticket and keep on walking back to their desk. Upon returning they get the ticket, walk back to the user's desk, plug the cable in and carry on. Or they can plug the cable back in and tell the user to raise the ticket so they can close it when they get back to the desk. The second option saves the tech some time (meaning they can get on to the next job quicker), and gets the user back to work sooner. So everybody (including the company) benefits from the tech working around the official process.

I believe the correct remediation would be to go back to the auditing folks and re-negotiate the way the process is defined, but management doesn't want to do that.

You're correct of course - and in an ideal world this is exactly what would happen. Sometimes however the time and effort to get such a process changed can far outweigh the gains of doing so where a simple and low-impact workaround exists. Management may have seen similar changes take a disproportionate amount of work to get done before, or possibly even seen similar requests be pushed back on.

Should I escalate this over my manager's head?

Obviously only you can make the decision as to how much this bothers you but going over your manager's head is something akin to the nuclear option and can very easily cause a serious amount of damage to your own career and is this really a hill worth dying on?

| improve this answer | |

If I am understanding your concern, what you're saying is that because you are in agile development, you cannot create a full document because pieces of the product haven't been done or planned yet. Then as it becomes available, you're to amend the original document to include that?

I don't see a problem with that per say. It sounds like the auditors need to understand that you guys are in agile development and the documentation won't be available until the sprint comes in. It sounds like a big chunk is missing from your statement though. What exactly is the part you're concerned with?

| improve this answer | |

TL;DR Design documentation is important for more reasons that just satisfying an audit. You can't hide behind Agile as an excuse for not maintaining good design documentation. Find a way to automate the maintenance of your docs and enjoy the benefits, including complying with company policies.

Is it unethical to produce a document solely to pass an audit? Probably. But you're missing the point of design documentation. It is important enough to your company that they have made the design artifacts a part of the quality/process audit that they perform.

You have not tagged your post with the industry you work in, but if you work in a safety critical (eg, automotive, industrial, aerospace), or a highly regulated (eg, financial, medical) industry, there may be regulatory requirements for design documentation.

Even if it's not required by a regulatory body, maintaining design documentation is good for bringing on new team members and helping them ramp up and become familiar with the structure of the project.

Working in an agile methodology does not excuse you from good software development practices. Somebody needs to be thinking about how each new story fits into the whole. You don't want to build a frankenstein product.

The trick is to find a way to automate the maintenance of your documentation so it can follow along with the development, and someone can easily review it and add technical debt cleanup tasks to your board as needed.

Javadoc, XmlDoc (.NET), and Doxygen (multi-language support) are all good tools for maintaining the "Design" of your system, and keeping it up to date. You can add a step to you continuous integration pipeline to create the docs every time a build is done. As with anything, though, thoughtless input = meaningless output, so make sure you're actually documenting things. Doxygen is a strong tool for this since it also makes it easy to create UML diagrams and call graphs embedded into your documentation. (I am in no way affiliated with Doxygen, other than being a happy user of it.)

By automating the maintenance of your design documentation, you will always have it handy for the audits, and it will always be current for your team's use.

It sounds as though your company lives in a waterfall world. If your team has decided to go agile, it is your team's responsibility to maintain documentation to meet your company's needs. Going agile does not excuse you from this.

If your company has gone agile, then the audits will eventually reflect this. But it may take a while. Either way, your team needs to comply with the audits, so make it as easy as possible for everyone.

It is unlikely this documentation will be a one-time thing. Do what you can to make sure it stays useful once it is created.

| improve this answer | |

I work in a similar heavily regulated environment. I don't see anything wrong with compiling the requirements document retroactively, particularly since the individual have been recorded elsewhere (in TFS, whatever that means).

The purpose of the requirements document is not to satisfy curiosity or deceive auditors; its purpose is to provide proof that the end product (design output) delivers what was originally requested (design input). As long as the document does not deviate from the actual state of affairs, it is fine to have it completed after the fact, particularly if it references TFS records where appropriate, providing a view into evolution of requirements. For future readers, whoever they may be, it is much more convenient to read a single properly structured document than dig through work items and tasks in an online tracking system.

Auditors in turn, if they are doing their job properly, should not be satisfied by the mere existence of the requirements document, but must verify that its contents correctly reflect the reality.

| improve this answer | |

Your manager is probably aware that to go to the audit team after the fact and say that they want to change the process is not going to be politically acceptable in any way shape or form. If I were the lead auditor just requesting a change to their requirements at this point )after project completion) would be enough for you to fail the audit. It means you failed to follow the defined process.

If I were to guess, he forgot about the audit team when switching to agile and is just now realizing the extent of his mistake.

The time to change the audit process is before the project starts. You might be better served looking at how to convince them that you need to adjust the process before the start of the next project.

However, you also need to understand that doing agile does not exempt you from company required processes. There are reasons such processes are in place including legal/contractual reasons. It might also affect various certifications.

So even though you may not like the task, it may not, in fact, be busywork. And auditors probably need those documents to see if what you created met the requirements. So I think the chance of getting out of doing those documents in the future is rather low, although you may be able to change the format. Developers need to understand that just doing development is not an option. there are other necessary tasks that other people in the organization need you to do in order to do their jobs.

At this point (based on what you said) if no one does the document, the project fails and does not get pushed to production. This is in no one's best interest. It would likely result in a good deal of increased workload as you try to justify the fact that you didn't follow a defined and known process. It could result in people losing their jobs.

Now on to your options. You can refuse to do the document which will put you in a bad place with your boss. You can escalate to his boss which is likely to get you in trouble along with him especially if everyone knew what the process was supposed to be. If the switch to agile was not sanctioned from above (and if it was it is far more likely the audit process would have been adjusted to reflect that fact), then likely you will lose that as well. You can choose to do the document as the least harmful action. Or you can choose to look for other work if the ethics of this bothers you so much.

AS for the lack of ethics, I don;t think it is really a problem. You say you have document as the Tasks in one of your systems. Then that is the start of the documentation and you are really just consolidating it and making it easier for the audit team to understand,. It is not as if you randomly did whatever you wanted.

For the future, put the tasks that need to be completed for later auditing into the sprints. There is no reason at all why you can't document each part of the process before you start coding. Instead of one giant design document created before coding, you create smaller design documents that get combined together at the completion.

| improve this answer | |

You must log in to answer this question.

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