Ask HN: How do you communicate technical ideas from devs to non-devs, vice versa | Hacker News Reader

Ask HN: How do you communicate technical ideas from devs to non-devs, vice versa

16 pointsTbobbyZ11 comments

What tools do you use? A template, format, or live doc editor? How do you do it?

My problem is my boss, who isn't a developer, will send me requirements to code something. This could involve 4-5 different objects in the db, and moving data between those objects and their fields. Basically I feel like I waste a lot of time understanding the db relationship between the objects and the intended steps to achieve to desire result (sudo code).

My main concern is to not waste time coding, by making sure I understand the requirement and steps needed to complete it. This is what I've tried to resolve my problem: once I receive a requirement, I will create a doc with my understanding of the problem. This includes sudo code, object and field names, and any additional logic. Once the doc is done, I give it to my boss to sign off on, to make sure I do understand what they want completed.

As I've attempted to make a tech spec doc, it just feels messy and unclear.

One additional goal I'd like this tech spec doc to achieve, is to be able to hand it off to any other developer, and they can understand if it's something can be achieved or not.

Sorry if these seems jumbled and unclear. I'm not quite sure what discipline is needed to solve my problem. It seems like a mix between technical writing and documentation.

First off, you're absolutely correct in trying to nail down the requirements before choosing. It sounds like there are a couple related problems that you're trying to solve. 1) You find the database design difficult to understand, 2) you're trying to understand and get sign off on functional requirements and 3) you're trying to write up a design for a technical solution. For 1) see if you can get an ER diagram so you can see the relationships. You may find that additionally you need to document sections of the db schema because you don't understand what certain tables represent. This can be done in a wiki or in the code or both. 2) Can be done using user stories or tickets, but for complex work it's best to write up a business requirements document containing the functional requirements (what needs to be done, not how to do it). There are templates and examples readily available, just adjust for the level of detail you need. This is what your boss should be signing off on. 3) You can probably avoid creating technical specs at the moment. Their target audience are developers and these specify the solution design. Unless you have a real need to choose one solution over another, it's often best to let the developer working on the problem to choose their own solution.

As an aside, you mean pseudo code not sudo code. Sudo is a linix/unix command

I would try to shift the communication from technical (how it is done) to non-technical (what it is supposed to do). But, dont ask "what is it supposed to do" in general. Ask more concrete specific questions.

I think that the discipline you are looking for is "analysis". it does not matter all that much which specific form document takes - requirements matrix, use cases, user stories, mockups, ... . Important is that it is stored on one place only, easy to update and updated often.

It sounds like your boss might be micromanaging. He should not be responsible for defining your data model; he hired you to worry about that. The only thing he should be concerned with is the business requirements, for example, which queries have business value? What queries might we want to make in the future?

It's good he's thinking about the data model, but he's introducing meaningless friction in your relationship by effectively requiring this additional communications step. You could spend that time coding.

In this example, your contract with him is to deliver a data model that optimizes for business requirements, minimizes cost, and maximizes speed. All those variables affect the data model, since you obviously need to consider tradeoffs when designing schemas or creating indices. You have the expertise to make decisions about these tradeoffs. Your boss only has expertise on the business requirements. So why would he try to optimize the data model himself if he is only considering a subset of the variables? He needs to trust you for your expertise and remember why he hired you, IMO.

The problem is he designs the data modal for the apps, and I'm suppose to work with it. These are apps that have existed for 1-2 years, mind you. Of course on a new app I design, but these existing apps, the design just seems terrible, and that makes it really hard to communicate what he wants to do with the modal and the apps features.

Get your boss a free copy of Visual Use Case. He can write requirements, user stories, list actors, etc and it will automagically spit out UML chart that you can use to visualize the flow when you code. You can get an upgrade to TopTeam Analyst and that will also give you swim lane diagrams plus manage end-to-end Requirements Traceability for Business Applications, Products and Medical systemsmore. Here is the free version:

http://www.visualusecase.com/download-visual-use-case-person...

Here is a video about the product you can share with him:

http://fast.wistia.net/embed/iframe/eamru13sx5?autoPlay=true...

And in the upgraded version you can host it on server so you can share it with team members......plus it has a client side to show customers mock ups and such. Although you can add screen shots to the requirements in the free version.

I was a software engineer who became a strategy consultant and part of my role is to communicate ideas back and forth between business and technical audiences.

Short answer: Lots of dialogue, feedback, listening and visual communication (i.e. whiteboard)

Long answer: It's more complicated because the person impacting you is your boss. Ask if he can involve you in the design process next time and let him know that if he can, you'll be able to understand things more efficiently and there's less risk of doing it wrong. When designing, share ideas but avoid directly saying he is wrong. Ask thoughtful questions like what is the business trying to do and what are they trying to solve? What will they eventually do with the database/system?

This seems very odd for someone to define a backend portion like this and ask you to build on top of it. The way I would approach this situation is list examples and situations where it makes your job harder and have reasons why a different approach would be better. If telling them that they will be stuck with these issues after you've moved on in a few years and they are ok with that then that's how it goes, nothing else can be done.

When you say 'requirements' what exactly is he handing over? I've built out a front-end interactive prototype using just HTML, CSS and a little bit of javascript when facing this issue. This forces my end-user to have something to touch/feel before coding out the back-end. It saves me time and it also forces the end user to start to really think through how their idea will work in the real world.

There is a whole db schema that he designed for the app that a company is using. He wants me to work with that when fixing bugs or adding features, those are requirements.

I think you need to focus on doing this visually, that is have him/her design the UI, agree on it, and distill that down to internal requirements which you can estimate out. It doesn't seem necessary to be sharing the implementation details with them.

Reply on news.ycombinator.com