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

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.

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.

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.

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...

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.

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.

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 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?