
Ask HN: How do you communicate technical ideas from devs to non-devs, vice versa - TbobbyZ
What tools do you use? A template, format, or live doc editor? How do you do it?<p>My problem is my boss, who isn&#x27;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).<p>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&#x27;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.<p>As I&#x27;ve attempted to make a tech spec doc, it just feels messy and unclear.<p>One additional goal I&#x27;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&#x27;s something can be achieved or not.<p>Sorry if these seems jumbled and unclear. I&#x27;m not quite sure what discipline is needed to solve my problem. It seems like a mix between technical writing and documentation.
======
twunde
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

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

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

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

------
ParameterOne
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...](http://www.visualusecase.com/download-visual-use-case-
personal-f.html)

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

[http://fast.wistia.net/embed/iframe/eamru13sx5?autoPlay=true...](http://fast.wistia.net/embed/iframe/eamru13sx5?autoPlay=true&controlsVisibleOnLoad=true&playerColor=4976d1&popover=true&version=v1&videoHeight=563&videoWidth=900&volumeControl=true)

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

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

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

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

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

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

