Iyfjky

Question

Here is the situation

The developer X receives the task to write the detailed
specification document.

The specification must be reviewed by the review board consisting of five or about software architects.

The problem is the endless review cycle: the developer is already preparing the eighth version of the document and the review board still finds numerous issues to improve. This has clearly got out of control.

What are reasons for this endless loop? Which additional rules should be added to the review process to prevent the endless rewriting? Both the developer and the architects have years of experience so obviously should not be incompetent.

The specification or the design? Why is a developer writing a specification? Shouldn't that be coming from your business analysts/key stakeholders? And why aren't the architects doing the design instead of endless review cycles and saying it's wrong? — Mar 8 '16 at 11:43
I agree: it sounds like the developer is trying to guess the design, and the architects are just giving him hints. No wonder it takes so many iterations! — Mar 8 '16 at 11:54
Is there a reason the developer and one of the architects aren't moved to the same room to work together on this? I doubt "more rules" is going to solve this problem. You need "more teamwork". — Mar 8 '16 at 12:19
@colmde Yet if the architects are constantly rejecting the specification, either the developer is not experienced enough, the overarching design is not clear, or the requirements are not clear. There is no reason this should have gone past two reviews without the entire situation being reassessed. — Mar 8 '16 at 12:20
What are reasons for this endless loop? Bad management? — Mar 8 '16 at 18:48

score 41 · Accepted Answer · 2016-03-08 12:43:08Z

The question is why does the board reject the specification over and over again.

Do they raise the same concerns on every iteration? Then they need to provide better feedback to the author why they reject it and what changes are required.

Did they give feedback to the author but the author refuses to make the changes? Then there needs to be a direct dialog between board and author about why these changes must / must not be made.

Do they raise new concerns about things which were already there before? Then they need to take their review job more seriously and provide bundled feedback. Instead of giving one reason for rejection, they need to give all reasons for rejection.

Do they raise new concerns about things which were not there before? Then it might in fact be necessary to put the document through another review cycle.

Is it just a power game certain board members are playing with the author? Then you have a social problem to solve, and you can't do that with a process.

The most productive approach might be to get architects and developer together on one table and have them come to a consensus about what needs to happen to get the document through the review cycle.

A bad review process (one focused only on the pass/reject facet) can halt on the first issue found, instead of exausting the issues with a given version. It happens in other areas (like application processing) when you go over and over every time bouncing on one little detail that was already there in a previous version. Can indicate lazyness by the part of the evaluator. — Mar 8 '16 at 16:52

colmde 4,078921 · Answer 2 · 2016-03-08 12:30:45Z

Can't really tell much without seeing an example but I'm sure your company won't allow you to put a technical document on the web! But there are several things you can look at:

The nature of the issues - are they continuously finding fault with the same things? If so then you need to figure out why the developer didn't get it right the first time.

Are the nature of the suggestions vague? e.g. "This area needs to be improved" or "We don't really like that". The reviewers need to be as specific as possible. Is the developer understanding why the changes need to be made?

Is there a business requirements type document that the developer can link each technical specification to? If not the developer may feel they need to try and guess at some of the business logic.

Do the reviewers change their minds? Do they conflict with each other? Is the review done in one meeting or is it like the document forwarded to them each individually and they all come back with different comments without seeing each others'? The latter could be a big cause of multiple reviews on items that could better be thrashed out and agreed upon in a single meeting. (Even if there doesn't seem to be a conflict between comments this could cause avoidable re-working)

What is the experience level of the developer? Are they properly understanding what the reviewer wants? Are they making their own decisions or assumptions based on what they think is best rather than asking the reviewer for clarification?

Ask the reviewers and the developer why they think the document needs to be continuously reviewed.

Could it be that the business rules have not been fully nailed down (or understood by the reviewers) and that there are new information or decisions at a higher level being made between iterations?

Olin Lathrop 4,13811218 · Answer 3 · 2016-03-08 12:37:33Z

This is a management failure. The process was set up incorrectly and the wrong people have been assigned to the tasks. The way to fix this is to change the process and assign the right people to the right tasks.

It's not clear where you fit in here. Keep in mind there are several different things called "specifications". At the highest level, there are the requirement specs. This says what the product is supposed to do, not how it's supposed to get that done. Then there is a high level architectural spec. That explains how everything will be structured. This is the block diagram level. Then there are detailed interface specs that tell individual engineers how their part has to fit together with the parts designed by others. The more junior the engineer, the more this might go into hints or outright edicts of how things will be done within the interface specs.

The high level requirements spec generally comes from customer-facing people that see a need or a niche. They should then sit down with senior engineering people to hash out what is possible within what they see as the opportunity.

In my preference, engineering then writes up a high level description of what the product will do, and passes that back to others until they agree that's what they'd like to have. Sometimes there is not enough overlap between what is wanted and what is possible, and the project ends there.

After that, it's all up to engineering. At this point you let a senior architect think about how to attack the problem and create the brief architectural spec. After that it's quite organization-dependent on how to spec out the details. In a small team, there may not be any formal spec at this level at all. In a large team, you often let this evolve as individual engineers start designing, with senior architecture people monitoring and guiding as desing progresses. Formalizing this step into detailed specs before design is done is not a good idea in my experience. You have to expect the low levels of the design to evolve over time, as long as the architect or chief engineer continues to be envolved and looking out for the big picture.

Note that the process you describe doesn't fit well anywhere above. Like I said, your process is broken. This is a management failure, and can only be addressed as such.

Cort Ammon 2,7021713 · Answer 4 · 2016-03-08 20:45:30Z

This is a natural consequence of the value of a reviewed-document being ill defined. Consider, what is the difference between a specification and a reviewed specification? In the case of a specification which would pass review, the content is the same, so the difference is clearly not in the content of the specification. The difference must be that the blessing of the review board has meaning to people. This is very reasonable in business: a blessing from a review board indicates that the use of the information is more justified.

However, there is a limit to this, which you may have reached. If the value of the stamp of approval from the review board becomes too great, they are forced to be extremely nitpicky. What they provide to the process is their name, declaring "yea verily, this specification is good." If a company refuses to use any document until it passes the review board, it is very easy to get into degenerate situations where the review board loses sight of their purpose. They get in trouble if they bless something that wasn't right, so if they do not fully understand how the blessed specification will be used, they will naturally rip it to shreds to make sure that nothing bad will ever come back to bite them.

This causes an issue for specifications that do not need this level of rigor. If your specification does indeed need to be blessed at the highest level because the business is going to make key decisions off that information, then that rigor may be desired. In that case, the decision should be important enough that the members of the review board should be able to work with the developer in an offline setting to ensure the specification will pass when it is reviewed. This is a common trick in business: never bring anything to the table unless you have already ensured it will pass.

If your business does not actually need this level of rigor, but it doesn't have a way to implement it, then the business has a major issue that is not the fault of either the developer or the reviewers. The business simply does not have a way to create actionable information at a pace fast enough to keep up with business. The business needs to change. You may be able to create a lower level review board which permits people to use the specification in a limited form, and only call upon the final review board when everyone is comfortable with the document (again, never bring it to the meeting unless you know it will pass the test).

The ways to do this are many, but the first step would be to identify if the specification actually warrants the level of exacting attention it is getting. The correct way to respond to the situation is strongly dependent on how commensurate the process is for the task.

HLGEM 133k25226489 · Answer 5 · 2016-03-08 20:51:51Z

When I worked in a different field, we had a similar problem on a technical review. The solution was for a very senior manager to take all the people who had to approve the document and the author of the document and put them in a meeting room that they were not allowed to leave until the document was finalized. At this point, this is the only way the spec will get out the door.

That said you appear to have the wrong person drafting the specs to begin with so it not surprising that they are not meeting the quality needs of the architects. Once you get this particular issue fixed, then you need to take a hard look at your entire process and make sure that you aren't setting people up for failure.

score 41 · Accepted Answer · 2016-03-08 12:43:08Z

The question is why does the board reject the specification over and over again.

Do they raise the same concerns on every iteration? Then they need to provide better feedback to the author why they reject it and what changes are required.

Did they give feedback to the author but the author refuses to make the changes? Then there needs to be a direct dialog between board and author about why these changes must / must not be made.

Do they raise new concerns about things which were already there before? Then they need to take their review job more seriously and provide bundled feedback. Instead of giving one reason for rejection, they need to give all reasons for rejection.

Do they raise new concerns about things which were not there before? Then it might in fact be necessary to put the document through another review cycle.

Is it just a power game certain board members are playing with the author? Then you have a social problem to solve, and you can't do that with a process.

The most productive approach might be to get architects and developer together on one table and have them come to a consensus about what needs to happen to get the document through the review cycle.

A bad review process (one focused only on the pass/reject facet) can halt on the first issue found, instead of exausting the issues with a given version. It happens in other areas (like application processing) when you go over and over every time bouncing on one little detail that was already there in a previous version. Can indicate lazyness by the part of the evaluator. — Mar 8 '16 at 16:52

colmde 4,078921 · Answer 7 · 2016-03-08 12:30:45Z

Can't really tell much without seeing an example but I'm sure your company won't allow you to put a technical document on the web! But there are several things you can look at:

The nature of the issues - are they continuously finding fault with the same things? If so then you need to figure out why the developer didn't get it right the first time.

Are the nature of the suggestions vague? e.g. "This area needs to be improved" or "We don't really like that". The reviewers need to be as specific as possible. Is the developer understanding why the changes need to be made?

Is there a business requirements type document that the developer can link each technical specification to? If not the developer may feel they need to try and guess at some of the business logic.

Do the reviewers change their minds? Do they conflict with each other? Is the review done in one meeting or is it like the document forwarded to them each individually and they all come back with different comments without seeing each others'? The latter could be a big cause of multiple reviews on items that could better be thrashed out and agreed upon in a single meeting. (Even if there doesn't seem to be a conflict between comments this could cause avoidable re-working)

What is the experience level of the developer? Are they properly understanding what the reviewer wants? Are they making their own decisions or assumptions based on what they think is best rather than asking the reviewer for clarification?

Ask the reviewers and the developer why they think the document needs to be continuously reviewed.

Could it be that the business rules have not been fully nailed down (or understood by the reviewers) and that there are new information or decisions at a higher level being made between iterations?

Olin Lathrop 4,13811218 · Answer 8 · 2016-03-08 12:37:33Z

This is a management failure. The process was set up incorrectly and the wrong people have been assigned to the tasks. The way to fix this is to change the process and assign the right people to the right tasks.

It's not clear where you fit in here. Keep in mind there are several different things called "specifications". At the highest level, there are the requirement specs. This says what the product is supposed to do, not how it's supposed to get that done. Then there is a high level architectural spec. That explains how everything will be structured. This is the block diagram level. Then there are detailed interface specs that tell individual engineers how their part has to fit together with the parts designed by others. The more junior the engineer, the more this might go into hints or outright edicts of how things will be done within the interface specs.

The high level requirements spec generally comes from customer-facing people that see a need or a niche. They should then sit down with senior engineering people to hash out what is possible within what they see as the opportunity.

In my preference, engineering then writes up a high level description of what the product will do, and passes that back to others until they agree that's what they'd like to have. Sometimes there is not enough overlap between what is wanted and what is possible, and the project ends there.

After that, it's all up to engineering. At this point you let a senior architect think about how to attack the problem and create the brief architectural spec. After that it's quite organization-dependent on how to spec out the details. In a small team, there may not be any formal spec at this level at all. In a large team, you often let this evolve as individual engineers start designing, with senior architecture people monitoring and guiding as desing progresses. Formalizing this step into detailed specs before design is done is not a good idea in my experience. You have to expect the low levels of the design to evolve over time, as long as the architect or chief engineer continues to be envolved and looking out for the big picture.

Note that the process you describe doesn't fit well anywhere above. Like I said, your process is broken. This is a management failure, and can only be addressed as such.

Cort Ammon 2,7021713 · Answer 9 · 2016-03-08 20:45:30Z

This is a natural consequence of the value of a reviewed-document being ill defined. Consider, what is the difference between a specification and a reviewed specification? In the case of a specification which would pass review, the content is the same, so the difference is clearly not in the content of the specification. The difference must be that the blessing of the review board has meaning to people. This is very reasonable in business: a blessing from a review board indicates that the use of the information is more justified.

However, there is a limit to this, which you may have reached. If the value of the stamp of approval from the review board becomes too great, they are forced to be extremely nitpicky. What they provide to the process is their name, declaring "yea verily, this specification is good." If a company refuses to use any document until it passes the review board, it is very easy to get into degenerate situations where the review board loses sight of their purpose. They get in trouble if they bless something that wasn't right, so if they do not fully understand how the blessed specification will be used, they will naturally rip it to shreds to make sure that nothing bad will ever come back to bite them.

This causes an issue for specifications that do not need this level of rigor. If your specification does indeed need to be blessed at the highest level because the business is going to make key decisions off that information, then that rigor may be desired. In that case, the decision should be important enough that the members of the review board should be able to work with the developer in an offline setting to ensure the specification will pass when it is reviewed. This is a common trick in business: never bring anything to the table unless you have already ensured it will pass.

If your business does not actually need this level of rigor, but it doesn't have a way to implement it, then the business has a major issue that is not the fault of either the developer or the reviewers. The business simply does not have a way to create actionable information at a pace fast enough to keep up with business. The business needs to change. You may be able to create a lower level review board which permits people to use the specification in a limited form, and only call upon the final review board when everyone is comfortable with the document (again, never bring it to the meeting unless you know it will pass the test).

The ways to do this are many, but the first step would be to identify if the specification actually warrants the level of exacting attention it is getting. The correct way to respond to the situation is strongly dependent on how commensurate the process is for the task.

HLGEM 133k25226489 · Answer 10 · 2016-03-08 20:51:51Z

When I worked in a different field, we had a similar problem on a technical review. The solution was for a very senior manager to take all the people who had to approve the document and the author of the document and put them in a meeting room that they were not allowed to leave until the document was finalized. At this point, this is the only way the spec will get out the door.

That said you appear to have the wrong person drafting the specs to begin with so it not surprising that they are not meeting the quality needs of the architects. Once you get this particular issue fixed, then you need to take a hard look at your entire process and make sure that you aren't setting people up for failure.

Search This Blog

Iyfjky

Which rules could help to prevent the endless reviewing loop? [closed]

closed as too broad by Jim G., gnat, Masked Manâ™¦, AndreiROM, Dawny33 Mar 9 '16 at 1:39

closed as too broad by Jim G., gnat, Masked Manâ™¦, AndreiROM, Dawny33 Mar 9 '16 at 1:39

closed as too broad by Jim G., gnat, Masked Manâ™¦, AndreiROM, Dawny33 Mar 9 '16 at 1:39

closed as too broad by Jim G., gnat, Masked Manâ™¦, AndreiROM, Dawny33 Mar 9 '16 at 1:39

5 Answers
5

5 Answers
5

5 Answers
5

Comments

Post a Comment

Popular posts from this blog

What does second last employer means? [closed]

List of Gilmore Girls characters

Confectionery

Category

Random preview

Which rules could help to prevent the endless reviewing loop? [closed]

closed as too broad by Jim G., gnat, Masked Manâ™¦, AndreiROM, Dawny33 Mar 9 '16 at 1:39

closed as too broad by Jim G., gnat, Masked Manâ™¦, AndreiROM, Dawny33 Mar 9 '16 at 1:39

closed as too broad by Jim G., gnat, Masked Manâ™¦, AndreiROM, Dawny33 Mar 9 '16 at 1:39

closed as too broad by Jim G., gnat, Masked Manâ™¦, AndreiROM, Dawny33 Mar 9 '16 at 1:39

5 Answers 5

5 Answers 5

5 Answers 5

Comments

Post a Comment

Popular posts from this blog

What does second last employer means? [closed]

List of Gilmore Girls characters

Confectionery

5 Answers
5

5 Answers
5

5 Answers
5