Profile picture

Communication Q&A and Videos

About Communication

How to write wiki type documents effectively?

Mid-Level Software Engineer [SDE 2] at Amazon profile pic
Mid-Level Software Engineer [SDE 2] at Amazon

Background:

Being pressured to deliver at high speed all the time, my team doesn't seem to value wiki type documentation a lot.

When starting a project/feature, we often have a high level design doc & design meeting to talk about high level infrastructure, and we make key trade-off decisions together as a team. If we are lucky, we get another low level design doc & meeting focused on sequencing of actions & interaction between class level objects.

We rarely seem to go back to our initial design doc after initial design phase of a project to update them and explain the actual final product we built and maybe some additional design decisions we made during implementation.

As a result, documentations are kind of dead after facilitating the initial design review. For legacy projects, high quality docs are extremely hard to come by and most just rely on reading large amount of code to understand how things work (nothing wrong with this but I think high quality documentation can save lots of time here).

I understand we don't want to boil the ocean and write everything in painstaking details, but we should at least have enough to help people understand responsibility of services and contract between them.

Questions:

  • Could you share your view on this topic and how you find your balance?
  • Do you believe it's always worth it to go back to documenting after finishing a project/feature and update it as if you are explaining it to someone new to the team/project?
  • Could you share any resources we might already have on this topic as well?
Show more
Posted a year ago
209 Views
3 Comments

How to avoid building the wrong thing when navigating ambiguity?

Anonymous User at Taro Community profile pic
Anonymous User at Taro Community

I'm an E5 at a big tech company. I've been on multiple projects where stakeholders waited until the very end of the projects to say, "That's not what I wanted." What can I do to prevent this from happening? I got feedback that I "need to navigate ambiguity". Does "navigating ambiguity" mean somehow predicting that stakeholders want something besides what they sign off on? If so, how do I develop this skill?

This seems to only happen on projects led by E6+ engineers or an M2. I have not had this experience when working with other E5's or more junior engineers.

Examples:

  • Misaligned OKRs: At the beginning of the quarter, my M2 told me that it was okay to have a multi-quarter effort, so I planned to do an analysis and roadmap in the first quarter, then execute on improving metrics in subsequent quarters. My M2 signed off on my OKRs for the first quarter. When I provided my deliverables at the end of the quarter, the M2 said, "That's not what I wanted." Then he told me that he wanted metrics moved, even though my OKRs clearly said it was just an analysis & roadmap. I asked 2 mentors (a Director & an M2 - both not in my management chain) for a 3rd party opinion and they both agreed that there was no way to read my OKRs as moving any metrics. I'm confused why the M2 signed off on it and didn't say anything about it in our team's weekly OKR review meetings if that's not what he wanted. He gave me feedback that I need to "navigate ambiguity." When I asked him for concrete, actionable steps to navigate ambiguity, he said, "If you need to ask that, then clearly you don't know how to navigate ambiguity." I'm so confused! Please help!
  • Low-level design missing on a cross-functional project: The DRI (an E6 backend engineer on a different team) kept talking in circles & refused to answer questions whenever the other mobile engineer and I asked about the low-level design for our project. The other mobile engineer tried escalating to our EM, but our EM did not help us. As a last resort, the other mobile engineer and I aligned on the mobile implementations and built that. During end-to-end testing, the DRI said, "That's not what I wanted." He did the same thing to the data scientist. The project was initially scoped for 6 weeks, but ended up taking 2.5 quarters due to all the churn around "late findings". My EM gave me feedback that I need to have a low-level design before starting implementation.
  • Wrong requirements on a cross-functional project: The DRI (E8 web on a different team) provided a requirements doc that was confusing, meandering/disorganized, and hard to follow/understand. An E7 mobile engineer flagged that the doc is not a proper requirements doc at a TSG (Tech Steering Group), but the DRI ignored him and forced me to implement it. I asked for requirements clarification, acceptance criteria, and end-to-end test cases, but he refused to provide any of them. He told me that the requirements doc was all I needed. I escalated this to 3 EMs (my EM, the project's EM, and the DRI's EM) due to my bad experience from the previous project, but none of them helped me. When I asked my EM point-blank how to avoid building the wrong thing, he told me to just make sure I get sign-off on the low-level design in my mobile RFC. I made sure to get sign-off from the DRI before implementation. I also provided TestFlights every 2 weeks for the duration of the project. On the final day that I was allocated to the project, the DRI asked what happens in an error scenario. I said, "Exactly what was documented and signed off in the low-level design of the mobile RFC. Why would it be any different?" Sure enough, he said, "Oh, that's not what I wanted." When I asked why he signed off on the low-level design, he said he missed the flowchart that described the error handling. This happened even though I explicitly tagged him on that flowchart in the Google Doc. So the overall mobile design was about 80% wrong. Turns out his requirements doc said the opposite of what he wanted and that's why the wrong thing got built. The TestFlights had the wrong behavior starting with the initial build, but he missed this as well. His feedback for me: "needs to make sure we build the right thing". How do I avoid this in the future? My EM was unable to provide any advice on how to avoid this in the future. All 3 EMs resigned towards the end of the project.
Show more
Posted 2 years ago
197 Views
3 Comments

How to set myself up for a good performance review?

Anonymous User at Taro Community profile pic
Anonymous User at Taro Community

I have joined this new company for little less than a year. I had interviewed for a different role but due to certain hiring constraints joined in a different team and role. The team I am in is not very technical, there's a lot of process and grind work that's part of the role. It is rather different from what I have been doing which was essentially automation of manual processes and deployment pipelines using tools and coding.

I had one review till now where I got an average rating, to me it seemed sub optimal given I put in a lot of effort to add value to the team. Some of the comments I received included that I should come up with my own ideas (this was with respect to a manual process that I automated which was lying in the backlog for over two years) and also related to some of the choices I made (manager asked if I want project A or B and I said I'm definitely interested in A).

To be honest, I feel my manager is nit picking and he also trivialized my work by making comments like anyone can code, ideas are important, etc even when no one from the team actively owned to execute the ideas.

I feel my manager doesn't particularly like me due to the above behaviors. In this situation how do I set myself up for a good performance review the next time. I would have considered quitting but I like the vibe of the company and some of the other teams are doing phenomenal work. It was hard for me to get in so even if I quit I don't want to quit without trying first.

In most of my previously held roles I became a go to person pretty quickly and got good visibility. How do I do this here?

Show more
Posted 2 years ago
195 Views
2 Comments

How to handle being on a team with slackers?

Anonymous User at Taro Community profile pic
Anonymous User at Taro Community

We are 3 people in my team. I've been at the company for 2 years roughly and my team mates for 15+ years. I'm in a situation where my coworkers do stuff, but stuff that's often completely unrelated to our backlog. One of them struggles with being motivated by the job. Occasionally, a 16-hour job takes a month to complete. Maybe 2. And you never know why or when it will be done. This causes a lot of tension with the product lead. The other teammate (focused on the front end) rarely makes any PRs. I'm not sure if it's due to the fact that they have mostly done HTML/CSS and are unsure of how to navigate the frameworks we use or what it is. Our manager tends to cover for us, but obviously he's not loving this situation. It's been like this for 1โ€“2 years. Now it has started affecting my pay raise, and I'm starting to feel tired of always playing dumb or referring to the other great work that they're doing when asked what my teammates are up to. Both seem to be struggling somewhat with stress and anxiety, so I've tried to be compassionate with them. But what do I do? I want to take ownership of the team's performance, but it's difficult to know what to do. They have the senior roles, and they have most of the ownership of the project, so I also feel weird telling them "what to do," if that makes any sense. The company size is roughly 20 engineers, FYI.

Any advice on how to handle this situation nicely, i.e. making sure we're still friends afterward, would be highly appreciated.

Show more
Posted 2 years ago
187 Views
2 Comments

Assigned too difficult work, what can I do?

Anonymous User at Taro Community profile pic
Anonymous User at Taro Community

I'm mid level, new to the company.

I got assigned a chunk of a bigger project owned by a staff level engineer, let's call him X, who has worked on the product for a long time and has a lot of context.

Things that were new to me: the language, the tool chain, product context. The codebase is several years old.

My skip level manager (1 level above my direct manager) once encouraged that I should aim to finish my work in less than 2x the amount of time it would take X to do it (but besides this I received no pressure, or reminder to push for this target from managers).

This was overly ambitious. I worked longer hours and harder than anyone around, including weekends but still could not finish it in 3x the amount of time initially estimated.

The staff engineer overestimated what I can do too. He's very willing to explain but I had a hard time mapping his high level explanation to what happens at the code level.

I could not tell if the standard here is high or the task is too hard. So I leaned towards putting in more effort rather than voicing my concern.

I also did not have a good sense of "are these unknown parts of the code base grok-able with a little bit of time or do they require a lot of time?" to estimate time spent up front.

In the end I got some barebone thing out and he took over. Still took him a couple more weeks to get the thing finished. Along the way he solved some problems I'm sure I have no chance of solving in that timespan.

With this evidence I was sure the task was legitimately too hard for me and was comfortable letting my manager know my opinion.

Back up a little bit, when I started working on the project, my manager knew I could not stick to the original timeline set by the engineer and encouraged me to take my time to learn the codebase. What is puzzling is my manager did not tell the engineer about this unrealistic estimate. The engineer reports to a different manager and has been around way longer than my manager.

Maybe there is some politics going on that I'm not aware of.

Anyway this has been a very stressful experience.

What could I do better? What should I do to mitigate any harm done through this experience?

Show more
Posted 2 years ago
179 Views
2 Comments