91

I am a technical writer who works in the office 1 day per week. The job I have does not require a lot of teamwork because I am the sole writer, but I do need to get information from developers. The info I need falls into the following categories:

  1. General information about the features, how they work and why they were implemented.
  2. Specific information (like how a feature behaves in a very specific situation and why it is behaving in a way I don't expect)
  3. Feedback for the work I have done (to ensure accuracy)

I have no problem getting 1, but I can't get responses for 2 or 3. The developers responsible for 2 have other priorities and their managers (responsible for 3) are very, very busy as the release approaches. My boss does not want to be involved in chasing them down.

If I go to their office in person, they say they will get back to me when they have the answer, but they never do. If I send an email, I either get no response or I get sent on an endless journey of "ask person x" responses.

On top of all of this, I am often very rushed to get the documentation ready, so it is a big problem that some days I do almost nothing but chase people down.

I know the problem involves all of the following points:

  • I am not in the office every day
  • Developers don't care about documentation
  • Everyone has too much to do before a release
  • My boss (who cares about the documentation) is not the developer's boss
  • Decisions I need to know about are not being made until the very last minute
  • features are barely being finished and tested before the release, so there is almost no time at all to tell me the final decisions and have me document it

How do I do my job without poison darts?

Edit: I do not think this is the same question as How to proceed when remote boss doesn't answer emails? because

  1. I am the one who is remote, and
  2. The dynamic is very different between an employee and boss.
  • 7
    Use a bigger font and write in red ! – ereOn Mar 19 '17 at 21:48
  • 4
  • 9
    Not at all. As a developer who worked with several different techpubs, if there is not an organizational-level commitment to documentation (and quite often there isn't), let alone some vague concept of priorities or who the end-user(s) are, let alone solid priorities, timescales, manpower estimates, milestones, then the documentation will be at best haphazard, at worst nonexistent. – smci Mar 20 '17 at 13:08
  • 1
    In those circumstances, a good techwriter has to also acquire traits of organizational consultant, project planner, negotiator and voice of the user. A bad techwriter simply ships a PDF full of crap which users never read and will skip to go straight to tech-support or knowledge-base. Or abandon the product for its competitors. (If you look at the last days of 3Com you can see a poignant example). – smci Mar 20 '17 at 13:15
  • 2
    @smci All of those questions and concerns might relate to generally being a good technical writer, having good technical documentation or general technical project management. But none of those things are directly applicable here. OP didn't ask how to do their job well (which would be too broad anyway), they just want to know how to get coworkers to give them the information they need to do their job. I might even go as far as saying OP being a technical writer is completely irrelevant to this question (and the answers seem to agree to a large extent). – Dukeling Mar 20 '17 at 15:27

11 Answers 11

115

That's what your manager is there for. If you have problems getting the information that you need to do your job, and since you have no authority to order anyone to help you, your manager should talk to the other manager and sort it out.

To repeat: You have no power. You can't make anyone do anything. That's not a matter of being independent. Your manager's job isn't to chase anyone. Your manager's job is to talk to another manager who can then tell his subordinates to help you. If she doesn't want to do that, then she isn't doing her job.

  • 48
    Well, but they are supposed to manage their devs. If the devs need to be managed and the managers won't do it, there's not much you can do. – MissMonicaE Mar 19 '17 at 21:12
  • 17
    @user66400 The other managers are so busy that it is difficult for them to respond to my emails, let alone, babysit their devs. Funny when the managers are too busy to manage... OP, what you are talking about is declaration of responsabilities. That's not babysitting. Either the employees who are not responding to you need to be told so by their manager or your manager needs to admit that you will have to do without, freeing you of the chase. Either way, it's manager work. They're paid to do it [citation needed] – xDaizu Mar 20 '17 at 11:32
  • 26
    This. As an employee who could be at the other side of things: If I have tasks from my manager, deadlines from him, I need him to evaluate me highly and so on, and someone would want to take some of my time for other purposes, I would flatly deny. You, @user66400 , wouldn't be able to get anything from me, no matter what you do, unless you would make my manager to schedule some of my time for you. Sorry, but I won't fail my tasks for you to do your job, and I will not do it in my lunch break or in overtime, at the cost of my health and / or family. And that's it. – Mołot Mar 20 '17 at 14:01
  • 4
    @user66400 Who says they can't close out the feature? What happens to the dev manager if the feature is not documented? – user151019 Mar 20 '17 at 19:11
  • 2
    @user66400 Either their manager is requiring them to close out the feature or he isn't. If he isn't, it's not their problem. It's their manager's job to decide what is or isn't their problem and it's their job to do what their manager tells them to. – David Schwartz Mar 20 '17 at 22:43
51

I used to do this for a living. What I find is people dread the idea that their time might be wasted. If you let them know up front you are going to respect their time, they'll be way more likely to make an effort.

Usually, after putting together the table of contents (and getting it approved), I divvied up all the topics and mentally "assigned" the missing details/gaps to people known to be the in-house experts or originating engineers. I'd tell them in advance I would be needing X amount of time to cover the following details, and include all the questions in the same email. I let them know there were 2 phases: the gathering info phase and later, the editing-for-accuracy phase.

Shy inaccessible engineers? No problem, if you email them in advance with your list of specific questions and a time estimate. Most people will cooperate if they know it's not an open-ended time sink.

Sometimes there are real language barriers, so you might need alternate sources. But those same individuals might be willing to review for technical details/accuracy on editing passes, after you get the whole manual/document fleshed out. A tape recorder also helped a lot (especially when someone is talking about hairy stuff you can't possibly understand on the first pass and using jargon you don't live with like they do). Not to mention mumblers!

One thing that helped me a lot was going to a couple of product design meetings (or whatever is the equivalent in your case) - especially if you can do it early on. That way you'll be "real", instead of an outsider who they may or may not even know about. Plus you can size up who's going to be accessible, up front. This may or may not be practical in your situation. Contracting is great, but like you said, the trick is that you are an outsider who has to produce like an insider.

41

I'm a technical writer who works with remote developers -- by which I mean 500 miles away, not "in the office only some days". There are two keys to solving this problem, and you've only asked about one of them so far (getting them to respond). I'll get to that, but first I'm going to talk about the other one.

Developers (or any subject-matter experts, for that matter) tend to not respond well people ask them things the SMEs have already answered. That's true for tech writers, testers, customer-support people, and probably others. So your job starts much earlier than documenting the mostly-working feature. Were there functional specifications? Design reviews? Discussions of requirements? Did you read those documents and go to those meetings? Did you ask questions about how the feature will work early on? (No you can't anticipate all questions then, but some might come to mind.) Are you part of the process?

If that's not how writers work in your organization, I urge you to do what you can to change that. If the culture is "dev throws a release over the wall to QA and doc when it's done", you're going to be fighting this "too little info, too late" battle forever. If it's the sort of organization where you can crash those meetings, start showing up. if it's not, work with your manager to get earlier access to information and plans before they're cast in stone.

(Yes, this means that some things that you learn early on you will have to unlearn later; plans change. Having done it both ways over my career, I can say with confidence that it is better to have the early access. Take good notes so you can check back later as truth mutates.)

There is a benefit to this approach beyond just getting access to the information. You want the developers to get used to seeing you at those meetings (physically or virtually). You want them to start thinking of you when they need to discuss a change with somebody. My dev team treats me as a member of the team in nearly all respects (I don't have to debug test-suite failures :-) ), and that's not an accident. I cultivated it.

Now, all that said, we come to the question you asked: how to get (a) any and (b) better responses to your questions. I agree with other advice you've received about sending email with your specific questions/topics and scheduling meetings when necessary, but beyond that: ask good questions. By which I mean:

  • Be specific. "How does the server work?" is broad and vague; the developer probably thinks you're asking for a class. "How does the server handle too many incoming requests?" is better.

  • Show what you've already done. Is this a question you can at least partially answer by using the software? Then do that. "I tried submitting a bunch of requests as quickly as I could move through browser tabs, but I couldn't get it to fail" shows that you've tried to help yourself. Or if it's not something you can reasonably test (you're going to need tens of thousands of requests, and you don't know how to write the code to script that), show background effort some other way: "I checked the design spec and I saw the section about how we have to handle this case, but I don't understand what you said about thread pools and priority queues".

  • If you keep having the same types of questions, ask how to fish: "I need to know what error code we return if X, and I know I asked about the error code for Y last week. Is there some place in the code I can look these up?" Sometimes you can't or it's not worth the effort or it will lead you astray, but showing that your first instinct is "try to figure it out" instead of "ask the dev" earns brownie points in my experience.

  • When you ask them to review something, (a) tell them what you're looking for and (b) target it appropriately. The devs are the best people to review for technical accuracy; you should be seeking your proofreading or your marketing spin elsewhere. If they've seen earlier drafts, highlight what's different in this one and how you responded to their previous comments.

Finally, if your organization has testers, then you have a natural ally. You and they both need much of the same information. Try to team up with them.

13

Your first paragraph contradicts itself:

I am a technical writer who works in the office 1 day per week. The job I have does not require a lot of teamwork because I am the sole writer, but I do need to get information from developers.

It's clear that you cannot work in total isolation from other people, since you are dependent on them to get the information that you need. Yet, you say that you don't require teamwork to do your job.

Your lack of time in the office is probably one contributing factor and going in more often would probably solve a lot of the problems that you are facing. It seems like you're fighting against "out of sight, out of mind". More face-to-face interactions with your manager, the developers, and the development managers will go a long way in solving this.

Another problem is that the role of a technical writer is misunderstood. A previous job was at an organization with a small technical writing team and many people didn't actually understand what value they added or what their roles/responsibilities were. From talking to them, this is pretty common in many companies, so you'll have to take up education. If you're boss doesn't want to chase people down, you'll need to be the one to chase people down. Since consistently chasing people down is a waste of time, you'll want to talk to your boss about being able to educate the rest of the staff on what you do with respect to whatever products or services your company provides, how you fit into the process, and the things that you need to be able in order to do your job on time.

Once you are in front of people more often and educate them on what it is you are doing, a lot of the problems you face will lessen. The development team not caring about documentation is a much deeper cultural issue on that team that is probably beyond your control. Extreme crunch time around releases is also indicative of other process or project problems that are likely at a higher level, as well.

If there is resistance to solutions - you aren't able to education, you aren't able to get time with people to do your job, you aren't able to get managers to unblock you - those are signs of deeper organizational problems.

  • 1
    "It's clear that you cannot work in total isolation from other people, since you are dependent on them to get the information that you need. Yet, you say that you don't require teamwork to do your job." That's not what the passage says. It says the job doesn't require a lot of teamwork, not that it doesn't require any at all. Consequently, re "Your first paragraph contradicts itself": no, it doesn't. – Lightness Races with Monica Mar 21 '17 at 11:15
  • 1
    @BoundaryImposition Yes, it does. If you need to get information from other people and rely on their inputs to do your job, you are on a team with them. Thinking that you don't need teamwork because you are the only one doing your job or are only going in to the office 1 day a week is clearly wrong, since this whole question is about working on a team with others. – Thomas Owens Mar 21 '17 at 12:18
  • 1
    @BoundaryImposition Thomas' point is that having an attitude that you don't need to interact "very much" with the team is a very wrong way of viewing your role. Your entire job depends on the product of the team's labor, and as a technical writer, you need intimate knowledge of the system's behavior. You're not going to get that knowledge by staring at the app. You need to know what it's supposed to do and the reasons it needs to work that way; you need to make sense of the intended workflows. As such, being overall uninvolved is contrary to the demands of your position. – jpmc26 Mar 21 '17 at 23:03
  • 1
    @BoundaryImposition No, you're focusing on minutiae instead of reading the answer in the way it was intended. The entire answer was written to emphasize the importance of being part of the team and to discourage the OP from viewing this as some small part of their job. – jpmc26 Mar 21 '17 at 23:08
  • 1
    @BoundaryImposition And specifically, it's not a "total fiction." The quoted sentence is clearly intended to indicate that the OP does feel they are some fringe appendage to the team that needs to interact with them very little. Thomas' answer is telling the OP that this attitude is contradictory to the role they have described. The OP needs to view themselves as integral to the team, not as someone who engages so little that they need not be concerned with teamwork. It is perhaps an insignificant 5% exaggeration, but it is certainly not "demonstrated to be 100% false." – jpmc26 Mar 21 '17 at 23:43
2

I hate to tell you, this is not a unique problem. Even when you are somebody's boss, this can happen.

The suggestion to get your manager involved is a solid recommendation. However, to say you are powerless is a bit of a stretch.

You have at least two tools in your box.

1] Anytime someone can blow you off, they will. Remember that! So what do you do? Do a walk about. Pick a time each week that suits you best (vary the day and time each week) and walk around to each of the developers and begin asking questions. Be cordial. Say hello. Introduce yourself. Explain your problem and how they can help with a smile. Say Thank You. Be as pleasant and gentle as possible, but be firm that you need your questions answered. If not now, it will be later. Make it clear, you are not there to make their life harder. If after lunch is better then fine. After lunch it is. If they continue to blow you off, simply explain that management will likely be asking questions and that you would rather say that ?? is extremely helpful instead of not particularly helpful. Two other tricks that help is to talk softly in a natural tone so that no-one else can really hear. You learn much more that way. Also, if you are talking to them, get as low or lower than they are. I have squatted on my heals to make this happen. Smile. Be friendly. After a while, you may be surprised that they begin e-mailing details as they go along. They know what is at stake for you and them and now you are a member of the team. This may take a few weeks to really begin working well. As long as they understand this is not a one-off behavior, they will relent.

2] If you are unable to do a walk about, then another great tool is accountability. I hate to be a pain in the *** (PIA), but sometimes, this is your only option, however, it should not be your first option. If you are e-mailing, cc your boss. Ask for a reply-all. If they do not reply-all, forward any response to your boss with a cc back to the individual. File everything forever. Same with your boss. Soon, everyone will begin to realize that there is accountability and that not responding is career suicide. Certainly, you have at least documented why you are having trouble doing your job. You can explain this to your boss. Explain that you are billing hours that are unproductive and that you prefer this was not the case. This is a good option anyway, certainly for CMMI, ISO, and other reasons, however, I prefer option 1 the best.

I found that both options work well. It takes weeks for it all to begin working well. However, with option 1, you are setting yourself up for unbelievable success. I used this technique when taking over failed projects for a global telecom that had the eye of the CEO/Chairman of the Board. The more I used option 1, the more people realized that I was doing them a favor and the amount of cooperation I got was staggering. In fact, I had more of an impact than their own bosses who loved me because I made them look good too without management really understanding why. Everyone wins.

2

You're a stakeholder in the development process, and as a person who has your own stakeholders, I'd say that you're a pig rather than a chicken (someone who has not just an involvement, but a commitment).

Insert yourself in the project management/scrum process. Attend status/standup meetings and tell the whole project team that your contribution is being blocked, that you won't achieve the commitment which was delegated to you, and you accepted, regarding the next shippable release. Get acceptance criteria (requirements) and actionable tasks onto the feature stories, so that that story's "definition of done" includes your contribution.

What this does is enhances other people's accountability to you, and your visibility to the others participating in the process. Including the business stakeholders. It also gives the people whose time and attention you need the permission to give it to you, since it's part of the capacity planning and the development estimate.

2

Email is a poor way to schedule and followup tasks. You need to raise the problem to your boss who should then schedule a meeting with the boss of developers. The aim should be to define some Definition of Done for developers, whereby a task or a User story should be marked complete only if the documentation requirements are met as well (similar to coding guidelines, unit tests etc.). This sounds like a hard approach, but o.t.o.h., this takes out any arguments or emotions out of the discussion. After several years of struggles, modern Software engineering have come to an agreement that quality steps such as static code analysis, unit tests etc. should be built into the process rather than leave it to chance. Documentation is still not fully there as it is difficult to automate and also how much documentation is enough documentation is still being debated. But nevertheless, if your company had decided that there should be documentation, then that task should be embedded into the process as well.

Your job as a technical writer should then be to discuss the quality of the documentation, not trying to convince all the time whether they would document at all

2

Timid e-mails get timid replies, assertive e-mails get assertive replies.

As others have said, whenever possible it's best to escalate this through the management chain. If the company has consciously decided not to allocate enough resources to documentation, that's something to bring up during the review after you've shipped. But the question seems to be looking for a workaround when management didn't see a problem coming until they were too overloaded to react.

Other people have described the steps necessary to convince people you know your stuff. If you've done all that and still can't get a response, try making up an answer that seems plausible, then e-mailing it to the devs and saying "I think this is right. Please confirm by <date>, when I'll add it to the official documentation".

If your communication clearly shows your clarity of thought and respect for your colleagues, they'll do a quick mental calculation: if I don't answer, this person is probably articulate enough to pin it on me; if I do answer, I'll earn the respect they've given me.

Obviously this approach has its risks, but if you've ruled out the right solution (escalating through management), this might be the bet you've got.

  • This would earn a reply like "I do not confirm. I don't have time scheduled to review this, contact my manager if you need it" from me. And OP would just lose a tiny bit of respect from me, because I would believe he should know the proper way to get some work from developers, without any need to be reminded. That's the risk you meant? – Mołot Mar 21 '17 at 19:56
  • Exactly, hence the importance of trying everything else before taking the risk. The question implies that management is too overloaded to schedule developers' time properly, which often forces people to use sub-optimal strategies. I'll edit the reply to make that clear. – Andrew Sayers Mar 21 '17 at 20:50
  • ...assertive e-mails get assertive replies. Reminds me of my favorite 'assertive' e-mail: "F#ck you! Strong letter to follow." (No "#" in original; I just feel it's not necessary here to quote totally accurately.) – user2338816 Mar 23 '17 at 10:17
1

Short answer, I would say, you can't "get" people to respond to your emails...

...and long answer, I would say, personally, the way I like to be approached with problems is to be asked for help...

...so for a longer answer, I would say, you can't "get" people to respond, but you can make your emails more "response-attractive."

This is to say, from the perspective of the developer being asked, I would be more inclined to help if I were only being asked to proofread, instead of being asked to provide.

When I'm asked to proofread, it's my personal expertise and experience that you need.

When I'm asked to provide, I (could) almost feel like you could have researched the answer yourself.

As they say, you catch more flies with honey than with vinegar.

At the same time, I would not wait for the developer if my deadline were looming.

I would continue submitting my work to my superior on-time with a list of documentation that may still need proofing (perhaps also adding the last time the developer and I had spoken for each item on the list).

In this way, I would still be covering all my bases while simultaneously learning new things that would help me in my profession.

But perhaps this is how you have been doing it already.

In which case, I'm sorry you're in such a pickle, but rest assured, then, that you are already being proactive and doing your job.

  • As an aside, I see your problem the same way that I see Stack Exchange; we come here for other people's advice by providing our own proposed solutions, but sometimes, we just need a nudge in the right direction whether it be from a developer or an anonymous person on the Internet. – Teacher KSHuang Mar 20 '17 at 8:47
  • I am talking about answering super simple questions via email. Many of them are yes/no questions. There is no other way I can get the info I need. – user66400 Mar 20 '17 at 17:51
  • 1
    @user66400 if I would have $1 for each question that someone thought is a simple "yes / no", and I actually needed a lot of time to explain why it is not that simple, before even attempting to answer... I sure could buy something nice now. – Mołot Mar 21 '17 at 19:59
  • Alas, I don't know :/. I'll have to take your word for it, @user66400. But you know, oftentimes, also similar to StackExchange, yes/no questions are the ones I'm least inclined to answer for the same reason as my answer above.... – Teacher KSHuang Mar 22 '17 at 10:14
1

One thing I do to make sure emails get answered is to email one person at a time. I've seen time and time again, if you email a group of people, it falls to the way side because no one is necessarily accountable. So, if anyone on the dev team can assist, pick one and email them specifically.

When you don't get a response, email their manager something like "Hey, I sent Steve an email requesting this information. I need this by the end of the day but have yet to hear back, can you make sure I get it?"

Now, you've made Steve and his manager accountable.

If you're still not getting responses, go up one level to that manager's superior and request help in the same fashion until someone does something.

Show paper trail as needed.

1

First, you're going to be the one chasing people down because no one else in authority wants to deal with this task.

Second, address the problem with your boss. Again, you'll do the work, but she may have some strategies. At some point, you will reach a time when you do not get what you need in time, so what do you do about it? How much time is reasonable for you to say, "If I don't have something I need 'x' amount of time before it is due, how to we reschedule/reprioritize?" Sorry, but those making decisions need to be confronted with the problem. Focus on the fact that you want to get things done on time, but you do not have the authority to hold everyone accountable to get you the information you need. Document all requests and deliveries.

On top of all of this, I am often very rushed to get the documentation ready, so it is a big problem

The fact you're being "rushed" is not a problem you'll get much sympathy from anyone. You need to get your boss to commit to a due date/time when if you do not get what you need by this time, it does not get done on time.

The bad part about your company is when different teams/divisions are evaluated in isolation. Programmers get away with not helping with documentation. In fairness to them, if they only are accountable for their code, that will always get priority over everything else. If documentation is important (i.e. your company makes money off of it directly or indirectly.), everyone responsible all along the chain of events getting this done should share the responsibility and the rewards. You and the developers should in a sense be on the same team when it comes to documentation. If the developers get information to you on time and you do not deliver, that's on your compensation and visa versa. There can be no scenario when one side inhibits the other without suffering the consequences.

Whatever value it is determined documentation brings to the company, everyone should reap the rewards when it is done and those suffer who do not do their part. Unfortunately, companies don't do this. Figuring out such a structure should be what managers are for. Otherwise, what are they doing that makes any money for he company?

Not the answer you're looking for? Browse other questions tagged or ask your own question.