2

I work as a Snr. BA in a large Manufacturing company and I've just implemented a new Requirements Management Process.

We have a large range of internal developers who in the past have never been asked to define solution via a Technical Design Document once they have received an approved Requirements documents. They normally just go ahead and code without any written reference of their solution or why it was chosen and any associated risks involved.

Now our release manager states that it should be the BA who writes the solution and Technical Design documents. I disagree as I believe it should come directly from the Developer, especially as there is an easy-to-complete TDD template.

I feel it's a waste of the BA's time to repeat and try to interpret a Developers solution and it runs the risk of misinterpreting the Developers solution. BA's aren't supposed to be THAT technical! :-)

In my experience it's been the Developer / Architect who writes it.

corning
  • 103
  • 3
Dazzar
  • 39
  • 1
  • 1
  • 2
  • recommended reading: **[How do I explain ${something} to ${someone}?](http://meta.programmers.stackexchange.com/a/6630/31260)** – gnat Mar 26 '15 at 09:32
  • 10
    It looks like you don't understand what developers really do and how hard it is. Adding them a paper work is not very smart idea. Eventually, it's not the paper work that gets the work done. It's the well-written code that makes the product ready to ship/sell. I've worked at company filled with various managers and analysts bossing around. They did not do their work well enough and loaded their incompetence upon our shoulders. Finally I quit. Processes are good if they're approved/owned/measured/improved/adding_value. Don't value your time more then that of developer's. Cooperate. Just opinion – xmojmr Mar 26 '15 at 13:15
  • Thanks for your comment Xmoj, but the truth is that the template I've created only requires a very 'high-level' of design so it's not overbearing by any means. I've worked with Developers for over ten years and really appreciate and respect the work they do. There's a major gap through where I work as there has never been any documentation on the solution design and it's causing major problems. Everywhere else I've worked the TDD has been written by Architects or Developers... – Dazzar Mar 26 '15 at 13:57
  • What is a "BA"? – senshin Mar 26 '15 at 15:16
  • 1
    @senshin typically the job title is "Business Analyst" though you sometimes see it as BSA for "Business Systems Analyst". In some places this folds into a PM ("Project Manager") role or BO ("Business Owner" - though I don't see that abbreviation as often as it kind of stinks) too. –  Mar 26 '15 at 15:18

3 Answers3

12

Unless the BA is also an technical architect, they should concern themselves with the "what it does" not the "how it does it". As a result, the BA writes the requirements and the technical architect writes the solution, and the developer writes the code.

Sometimes (or quite often) these roles are shared by someone, so a dev could also be the architect of their own code, or could be an expert in an area writing the Tdd for a junior to develop. Occasionally the BA will also be the TA, but only if they come from a technical and not business background.

Where I work now, we have a technical design authority who takes the basic requirements from the business people and turned them into technical requirements (ie makes them sensible), the senior developers write a solution document saying how they intend to fulfil the requirements which the TDA reviews, then the developers code it all up. The technical requirements are also used by the test team to write their system tests.

gbjbaanb
  • 48,354
  • 6
  • 102
  • 172
  • Thanks for your answer Gbjb, yes I agree. Seems like a great idea to have a 'Technical Design Authority'. I'll see how this suggestion works. – Dazzar Mar 26 '15 at 10:27
2

At my current job, we have BAs who are more technically inclined than where I've worked before, but we still have never expected them to write technical design docs. Developers always wrote those, and then architects signed off on them.

In support of xmojmr's comment, though, I would point out that while we were very diligent about documentation during our waterfall era, we noticed some weaknesses with it:

  1. Technical documentation was expected to be completed before development began. In reality, the best we could do was document an educated guess at the technical details, and revise it frequently as development progressed.
  2. Much of what went into the document was boilerplate, and thus had little or no real meaning to anyone.
  3. The intended audience for the technical document was the developers (anyone who would be maintaining the code down the road). In this regard, it was utterly useless. Someone who needed to fix a problem or tweak some output would find nothing of value in the tech doc. The kind of detail needed by maintainers lives in the code itself. If you try to beef up your tech docs to approach the level of detail present in the code, you'll not just duplicate effort, but the code and the doc will inevitably fall out of sync (probably before version 1 even ships).

When we switched to an agile workflow, we deliberately ditched technical documents, and nobody misses them. We adhere to the idea of "just enough documentation," which means if there are decisions that need to be written down, or sticking points that need to be explained, we have a wiki for that kind of thing. Some processes still have formal flow diagrams, because those are useful to the product owner. But shifting focus away from documentation and more toward fulfilling customer needs has made all of the stakeholders happier, and the product is actually more stable than ever.

Daren Beattie
  • 29
  • 1
  • 1
    Just an observation, all the weaknesses you observed are solely because of not understanding a proper development process. 1- Technical documentation does not need to be totally complete before development. Just the part(s) you are going to be working on. 2-If your design documentation is mostly boilerplate then you aren't doing something right. About the only boilerplate in our documents is the format. 3-The design documentation is not for the maintainers, it is for the people doing the development. The design tells them what and how to implement the code. – Dunk Mar 26 '15 at 14:00
  • 1
    To expand on point 3. Creating design documentation lets you parcel out the implementation to other developers. A person skilled in design usually makes the coding part rather trivial. – Dunk Mar 26 '15 at 14:04
  • Thanks for your comments, you've both raised some interesting points. I agree with Dunk though specifically on his points 2 & 3. One of the core reasons we're requesting a new TDD to be created is so that we can better plan Developer resource so we can inform our Business Units of expected release dates. Does anyone know or have any 'Best Practice' links on this? - Thanks! – Dazzar Mar 26 '15 at 14:47
0

The response to this question is highly dependent on the organization of each company. As mentioned, the ideal is that the technical documents are written by the Software Analyst, after having discussed with the software developers/engineers of the project. However, when there is no Architect in the group, the workload has to be shared. In other words, why don't you stop considering writing the technical documents as a burden and start considering it as a perfect chance to obtain more technical knowledge ?

In my opinion, you cannot write this document on your own, because you lack significant technical background. However, neither the developer is fully capable of writing a well-structured technical document, since he misses other qualities. Even if the developer is really qualified and can write a perfect technical document, I think he will lose significant amount of time, that can be spent much more efficiently in the implementation phase.

So, I suggest that you write the technical document, after having multiple discussions with the Developer. In this way, there will be 2 benefits : - You will acquire significant technical knowledge, e.g. around design patterns, protocols etc. This knowledge will be an important asset for your future. - The project duration will be shorter, since the Developer will have more time for the implementation. And he will also appreciate you more ;)

Dimos
  • 419
  • 2
  • 10
  • Hi Raptis, In 'the perfect world' I would agree with you and would welcome the opportunity to learn more on the Technical side. However we're currently in a situation where we have a backlog of over 400 projects requiring Requirements to be defined so there is no BA resource available to also start writing TDD's. Also our Integrated system has six separate systems linked to it so it would be a massive amount of work to understand each of these six systems from a Technical point of view as well. The BA is not an Architect nor a Developer and I feel that everyone expects the BA to be everything! – Dazzar Mar 30 '15 at 05:41
  • Dazzar, what you described might also be the scenario for the developers as well, with many projects waiting for new features to be released or bugs fixed. However, if this is not the case, and given that there is a TDD template, it is quite possible that the Developer will be able to fill it faster than you. Beware though that this Developer needs to be senior and have experience, since errors in the stage of Technical Requirements Documentation can lead to serious delay of the project. – Dimos Mar 30 '15 at 08:23