Ask HN: What is the first thing you implement at a new company? | Hacker News Reader

Ask HN: What is the first thing you implement at a new company?

331 pointssystemtest276 comments

For job-hoppers and contractors. If you arrive at a company, what is the first thing you push for?

For instance, I usually implement a good feature-branch flow with branch pipelines and a strict merge-to-develop etiquette with mandatory merge requests. It makes my work easier and once the team is used to it, they also really like it. No more messy development branches.

I also request a small office stool next to my desk to make code reviews, three amigos and pair programming easier. It is a small thing but I noticed that people are more eager to discuss things if they have a place to sit.

View on HN

For the first month or so I take a very humble listening position, even if I immediately see things I want to fix. More often then not, there is a background and a history to things that could lead to a) my “fix” being unnecessary and/or ill-informed and b) friction with the rest of the team because here comes a whippersnapper upending all our stuff.

Process and code fixes are _much_ easier once you have good rapport with the team.

Yeah, I have to say I'm a bit surprised to see people so eager to change things that are working, so fast.

Sometimes those things that are working imposed a hefty load of technical debt, which newcomers are tasked to pay up with compound interest due to the unfamiliarity with the codebase. Therefore rewriting some components may actually pay off in productivity in the short run.

See also Chesterton’s fence. You don’t want to change something until you understand why it’s there in the first place.

https://abovethelaw.com/2014/01/the-fallacy-of-chestertons-f...

This reminds me of the Joel Spolsky's post on why you should never re-write your code from scratch [1].

The reasoning goes most 'ugliness' comes from bug-fixes that people encountered along the way, and by re-writing that 'two page function' you lose all that accumulated knowledge. In short, the hacks that make us want to rewrite code are there for a reason

[1] https://www.joelonsoftware.com/2000/04/06/things-you-should-...

More likely the hacks are there because requirements changed and the software wasn't initially built to be flexible enough to support change.

A rewrite will solve it in the short term - until requirements change again.

However, I would much rather apply the new 'hacks' onto the rewritten 10 line function than figure out the original 200 line behemoth.

Each hack individually, yes, is likely to be there because of requirements changing.

But collectively, it's likely that one of those hacks is there to account for some edge case that's not intuitive and will be missed on the rewrite.

In my experience, it's extremely difficult to know which particular lines of code are obsolete. This becomes even more difficult as a codebase ages and is worked on by more contributors. Add on another exponent for every business stakeholder that has a hand in defining the business rules—especially if you have requirements coming from multiple sources that may not be aware of each other.

This is why we have the strangler pattern, right? You wrap the legacy functionality with a set of tests that define the functional requirements of the code, then your new refactored solution needs to keep those tests passing. (And then once you've done that, make sure that your "hacks and bugfixes" get test cases so you can make sure the next refactor accounts for them!)

Which is why comprehensive testing is important. If we have test cases that accurately capture our requirements, then we can refactor and know when we've err'd from the path. If we don't have test cases, then we have to make best guesses (and we know how that one turns out).

Accuracy is key, here. I came into my current job with some pretty awful tests in place that “passed” and showed good coverage but did absolutely nothing for actually hitting the necessary cases...

I have some code I inherited that I have rewritten it twice now and the second time is when it really became stable and also easier to work with.

Or you rewrite it to be more flexible and seriously think about what if's eg what if sales tax was changed in the middle of a month/billing period.

This is a real example at one job in the UK on budget day I used to listen the budget speech live in case it had any impact on the system I worked on.

I worked with one guy once where he wanted the "ultimate flexibility" and every data model object basically became a database table with the columns 'key' and 'value'. Trying to think of everything ahead of time has its own problems...

Which is how map/reduce systems work at the core - and how we implemented it back in the 1980's.

Each record type and field in that record had its own entry in a MIDAS table so you could process say TELEX records differently to Email, Data etc.

If it's well tested a straight re-write is the right call. It's when there isn't good test coverage where things ossify.

In theory. In practice, the code will often have corner case behaviours that eludes any of the tests, yet are still important.

As an aside, as I understand it, refactoring was popularised as a response basically to this conundrum - it's a technique for reorganising code without changing its functionality. So you can gradually "rewrite" your two page function without losing the accumulated knowledge.

Unless we really stretch the word "refactor", my "in practice" is different than yours. I've done plenty of re-writes that fixed more unknown bugs than re-opened previously solved ones.

I agree with other responses to this comment. Ugliness might have had a reason, ok. It's important to understand that. The question is whether it has a reason to stay. And here we find the usual balance between the effort it takes to maintain ugly code and the effort it takes writing new one. On another point... I understand calling that "accumulated knowledge". But that's knowledge accumulated very badly. You want to accumulate knowledge? Write tests when needed, comment them when needed, add comments when needed in the comment. That's accumulated knowedge too, and you are actually making it way easier to transfer, which is definitely one of the most important parts. If you were already doing things right, that's another story, but in general, if you look at code and your brain goes "what the..? no, please, why did you... T_T", there's probably a need for a rewrite.

EDIT: I think it's also important to mention the value in rewrites, specially on your own code. Spend a lot of time thinking how to make your code simpler, easier to follow, cleaner. That will help you write much better code in the future. A lot of people would benefit from this if they tried. Writing code that works is simple, writing good code is very hard. And rewriting code teaches a lot of the second. When you are learning, rewrite a lot. When you think you know what you are doing but someone suggests to rewrite (and you know they are good programmers too), at least listen.

Actually, what that piece underpins is not that you shouldn't do rewrites, but that you shouldn't do that with the expense of the developer resources of your legacy application, you shouldn't put your old product "on hold" for the period of the rewrite, nor should you pretend that you are modifying the old product, but that rewrite effectively always results in a new product, and you shouldn't except that you can hotswap the new product with the old one.

The age old maxim "sell old products to old customers, and new products to new customers" works pretty well here as well.

How to rewrite the product if all your experts are tied up in the old product is a different question entirely.

For example of industry that seems to be in perpetual rewrite is the gaming industry. But they don't rewrite the old games, the develop new products using partly the existing concepts and software modules.

This product based view also tells you something: when in business, you should never do a rewrite out of purely technical aesthetic reasons, but because of concrete measurable business goals.

That article by Joel Spolsky was one of the few I can't fully agree with. The greatest successes of my career have often been in creating "next generation" implementations of software using newer or better technology and designs. Those re-implementations have resulted in very significant performance and productivity gains. While rewriting things from scratch can definitely be a naive impulse, there are times when it's the right way to improve a product, and if you fail to do so, your competitors will. The trend towards microservices tacitly recognizes this, I think; one of the tenets being it should take a small team a couple of weeks to rewrite any component of the system from scratch. When software was written poorly to begin with and has grown unmanageable by layering hack upon hack, it can pay to take a step back, look at the actual requirements, and consider if there's a better way.

I wholeheartedly agree with what you said. There is a time and a place for leaving legacy code alone. I also know from first hand experience some things are just too far down the hacky rabbit hole and you just gotta cut of the dead stuff and start over sometimes. But on the other hand, the only times I've done that in my career the code was written in a very anti-pattern style pretty much against all language guidelines and had hidden side effects everywhere. It was a mess to figure out how some features worked so I just rewrote some features in 1/10th of the time it took the original maintainer to piece in similar bug fixes in the legacy code.

The piece focuses on ground-up rewrites of commercial products. If your project doesn't apply, then neither does his advice.

I have done my fair share of rewrites as well. The hardest ones are where you need the new system to be backwards compatible.

Rewriting the code from scratch does not necessarily mean clean-room reimplementation! It doesn't even mean you can't include parts of the original in the new code.

Rewriting from scratch means rethinking the design, or basic structure, of the code while keeping all its functionality. It's not about getting rid of hacks, it's about lining them up neatly in one place instead of having them all mixed, twisted, nested and threaded through the code everywhere.

Well, at least if you know what you're doing, instead of just randomly deciding on a rewrite because it's more interesting that way or because you can't be bothered to read and understand the original. Then, I agree completely with Joel, it's most of the time a grave mistake which made countless companies and developers fail.

Exactly this. It’s usually much better to refactor/rewrite small pieces at a time where you can rather than taking a scorched earth approach on the entire codebase, and usually that involves including some of the “hacks” until you can get a better grasp on what the right design is.

> at least if you know what you're doing

Isn't this exactly the problem? I know "what I'm doing", but don't have the added knowledge of several engineeers through several years, and rewrite it's not necessarily a 1:1 transcription to a new language or structure.

If something is bothering the team daily, than yes, a rewrite might be needed, which is different, and hardly something I would exclusively by myself.

> most 'ugliness' comes from bug-fixes that people encountered along the way

That's reality, sure, but there's no reason not to document it properly. Inadequate documentation seems to be assumed implicitly here.

If a (competent) reader is thinking Why on Earth does this code do that?, it means you've written unmaintainable code with too few comments around the necessary-but-ugly workarounds that you've used.

If you have properly commented everything, the reader won't mistake the necessary complexity of the code for a giant-ball-of-mud.

My take on this is that it won’t help anyway. If there are problems in the code that have nothing to do with Chesterton, the fact is that the team wrote this code and asking for a do-over is magical thinking.

If you want to fix it, fix it. Find the other people who are fixing it and collaborate.

Advice I should follow myself: If they fight you on that, get out. They like their ball of mud, and they will turn new code into mud too. If you ever succeed, it will take you until it’s time to find a new job just to get things to tolerable. That’s an incredibly foolish investment in being right.

There are more people in the world that can be taught than there are teachers. Don’t waste your efforts on bad pupils. It just reduces our collective intelligence.

I think using "never" should be considered an exaggeration or embellishment, or else clearly disclaim that rewriting code given the existing needs of the business (including the existing code base) is different from writing brand-new code "from scratch".

Here's why: I saw a comment in some thread about machine learning yesterday that I think is a good analogy in some cases for what you describe. The comment essentially said that a "never re-write" policy leads to "overfitting" the code to the problems of the past and therefore less flexibility in implementing both fixes for issues and new feature development.

Mostly you shouldn't rewrite your code from scratch :-) - some times you need to like when we in the UK had to rewrite a billing system - which was a POS we had inherited from MCI.

People have been measuring the cost of refactoring versus rewrite from scratch, but the results are, as so often in the industry of software development mostly ignored. Anyway, there (obviously) is a tilting point.

But what are the results?

if more than 25% of a component is to be revised, it's more efficient and effective to rewrite it from scratch. (It's fact 19 in 55 Facts and Fallacies of Software Engineering) which references several sources of it.

Chesterton's fence has always bothered me a little because it presumes there will be a sensible explanation for the fence, and that the reason will reveal itself to us if we have the patience and guile to see it.

Knowing what I know about how some organizations work, I don't think this is necessarily a safe assumption.

You can't expect it to just come to you, you have to ask. Unfortunately many organisations are bad at institutional memory, so reasons get lost. But fundamentally this requires a "why?" conversation, it can't be done by purely technical means.

If you're very confident that your test suite covers all use cases, then you can just change it and see what breaks.

I understood it differently. As in: there is always a reason for the fence but you never know whether it is justified or not without understanding it. Don’t tear down the fence until you understand why it was put there for the wrong reasons.

True, but what I think s_kilk was getting at is that sometimes (especially in software) a bad developer will put a "fence" somewhere without a reason. And if that person already left the company, maybe you can never find out why.

That's why it's important to start with some testcases of required behavior, and then refactor only code that is supported by tests. Because sometimes the fence is there for a reason, but often it's not.

> some testcases of required behavior, and then refactor only code that is supported by tests

The difficulty is making sure that you have all the requirements and aren't missing any, and once a system gets big enough, that gets really difficult.

Even bad developers have reasons, you may not be able to divine those reasons but they may be legitimate. The would-be refactorer would do well to consider carefully what the reason might have been, even if a git-blame reveals a less-than-excellent contributor.

As an programmer I always try to capture these reasons in my commit messages, after a decade of doing this I’ve gotten a lot of thank you notes years after leaving a project, and I’ve even reminded myself details about my own thought process that I had otherwise would have long forgotten.

One thing I’ve learned by having long tenures is that context change over years is much more likely the reason for nonsensical code than developer stupidity.

No, the point of Chesterton's fence isn't presuming there is a reason:

> The more modern type of reformer goes gaily up to it and says, "I don't see the use of this; let us clear it away." To which the more intelligent type of reformer will do well to answer: "If you don't see the use of it, I certainly won't let you clear it away. Go away and think. Then, when you can come back and tell me that you do see the use of it, I may allow you to destroy it."

The point is that there might be a reason, and before careful consideration we won't understand what that might be.

Chesterton’s fence is an idea to help you counteract the exact notion you are expressing here. You must prove that the reason for its existence is no longer sensible (or, perhaps, never was sensible) before removing it. There is no probability distribution associated with the proverb, except that there is a nonzero chance of sensible explanation.

A line I just used yesterday in a company presentation about feedback loops "if you don't understand a system's key feedback loops you don't truly understand the system"

> Process and code fixes are _much_ easier once you have good rapport with the team.

And one doesn't get that by walking into a place expecting to make sweeping changes.

What's worse is job hoppers were asked so this means people are going into a shop, making these changes, and leaving shortly after. The hell?

More realistically they’re going into a shop proposing changes immediately, getting slapped down, becoming disillusioned, leaving, and then trying again somewhere else. Even when people do make changes like this, it’s unlikely they stand the test of time, I’ve definitely seen people’s “pet changes” get rolled back within microseconds of them exiting.

You're absolutely right. "job hoppers" are often the very motivated people that are worth their weight in gold, but don't find a company that is on their level.

However as a manager you should probably not institute sweeping changes a "newbie" (he could actually be more of an expert than your own team, but you don't know this yet) suggests, but finding out why the newbie suggests them should be in your best interest. Often fresh eyes are the only ones that can see what is wrong. Dan Luu put this really well: https://danluu.com/wat/.

A lot of catastrophe's could have been avoided (especially stuff that's morally questionable) if people listened more to the newbie who still isn't conforming enough to your team that he still sees what's wrong.

So my advice (to the managers): listen to the suggestions, and put your managerial clout and preexisting rapport with your team (which the newbie lacks) to implement the good ones, if there are good ones.

If they aren't you can still explain why.

Agreed. I have a theory that the reason contractors want to change everything when they arrive is so that they have infinite work.

I also always see contractors wanting to start self-initiated projects from scratch rather than working in the codebase, which is of course easier to produce a visible result in.

As a person working in this scenario I find the biggest issue coming into work on an established code-base is the lack of documentation and a lack of interest from the company's own people to divulge any information about the code base. This unfortunately leads more often than not to the situation you describe, re-written code or projects perhaps unnecessarily separated.

Very true as well, and if that were plainly stated the problem could be addressed. The issue is that some of these people are smooth talkers able to convince managers that these big shifts are necessary right away...and inevitably end up abandoning big projects they push for.

Others are able to poke around the codebase and ask questions till they can contribute in a meaningful way, but these are rare in my experience.

> Very true as well, and if that were plainly stated the problem could be addressed.

That's not, at all, how this works, especially for newcomers.

If the new programmer on your team doesn't want to work on a larger code base, it's your responsibility to notice this early, initiate a talk with them about the reasons and actively try to fix the problems they have.

Reading code is hard enough, but reading it under pressure of being the new guy makes it even worse. Don't expect many people to be able to cope with this without serious effort on your part. If you can't be bothered to effectively support them in understanding your code, they are not likely to care about that code sufficiently to productively work on it.

When you come in on a contract you need to fix or add something specific. Keeping the existing codebase is usually last on the list of priorities.

When you're brought in to add something at a critical time but instead push for bigger changes because of inability to work with an existing codebase that means they need to find a better programmer for the time being to do the role you were hired for.

It's rare that existing employees don't realize a codebase is crap, and starting over they could do better...that's not why contractors are hired, to state the obvious.

+1 for this.

Unless you've been hired specifically to help them change their dev practices, I'd go along with what they have until you've got some understanding and reputational-clout to start suggesting such huge changes to how everyone works.

Rocking up and on day one start asking people to change their development practices (particularly around branching policy which is something very contentious and/or strict everywhere I've been) because "It makes my work easier" is a sure-fire way to get people's backs up and dislike you. And where do you stop? First it "It makes my work easier" to change the dev practices, but why not start demanding that everything is rewritten in Go/Vue.js/Haskell? It'll make your work easier. How about we change the product from a Desktop App to a web app? It'll make your work easier. Why dont we just sub-contract the whole thing out to off-shore teams? It'll make your work easier. There might be a case for any of those, but I'd personally wait (and I would prefer any hires I bring in also wait!) until the right time before advocating for massive sweeping changes right away.

tl;dr - Arrogance & know-it-alls can be disruptive (in a bad way). It takes a village and flexibility is key to working with any team.

The fact that process is off in the first place indicates a deeper problem.

In which case the correct answer is to sit tight for a bit until you understand the deeper problem. And then you fix the deeper problem, and then you fix the process.

If the process is 'off' around branching policy, there may actually not be a problem. It's certainly possible the new dev prefers a different branching policy simply because that fits with what they are used to. There may be reasons, and good ones, for what may at first appear like poor git practice. Or it may be a problem, but a new dev should at least give it enough time to determine there is no reason things are this way before advocating change.

'Everything got the way it is one logical step at a time' - paraphrase of some of Gerald Weinberg's advice in 'The Secrets of Consulting'

I was going to say "Happy Hour" but this is really what I meant. I focus first on understanding how the team works, their motivations, their past pain points, and honestly become one of them before I suggest changing what is then _our_ process.

I wouldn't, on the first day, try to take up more of my coworkers time. I would wait until I learned the norms about after-work outings and what sort of obligations they have outside of work.

This is one I learned the hard way. I made a number of much-needed fixes at a job where they'd never really had a dedicated technical person before. People freaked out. I hadn't communicated what I was doing and why it was necessary, and it took a while to earn goodwill after that. Lesson learned: don't implement a solution until you've convinced everyone they have a problem and this will fix it.

I whole-heartedly agree. I've worked with too many Senior Engineers who immediately want to change processes in their first two weeks of starting at a new company. It only alienates the other developers.

I was asked in an interview "What is the first thing you will change?" (I was interviewing for a Manager position, but I think this applies no matter the position you are being interviewed for.)

My response was - "I don't know. I need to spend time getting to know the team, understand our product, and better understand priorities."

I try to use this question in interviews with senior people, be they Developers or Managers. It can expose someone who will quickly blow your team up should they join. I like working with people who have great passion and will stand up for their ideas, but understanding the problem first is alway wise!

Getting to know people, products, and customers, (not that customers aren't people) with listening and questions makes everyone better.

> "What is the first thing you will change?"

My response: "My mind" ... As i seek to _first_ understand and then to act...

10 Points

This honestly took me a while to learn - it's so easy to jump in and be a smartass (and I've been guilty of this before) about how bad things are, but a) suggesting small, incremental changes that demonstrate a nuanced understanding of where things went wrong and b) volunteering to work on making things better goes a long way. Most of the team will already often know and agree on what is bad - but just won't be empowered to fix it somehow.

> This honestly took me a while to learn

Yeah same here. I think I pissed off my manager pretty quickly at my current job by trying to change how they did certain things before getting an understanding of why they did them that way, but I realized my mistake and went into more of an observer-mindset for awhile.

Over time I built up a reputation with reducing friction in smaller ways on specific features I worked on, and then applied that same thinking to larger scale issues I saw. They were much more receptive once they knew I could make valuable contributions, and now I'm one of the main people establishing patterns and architecture decisions at my company.

Learning to establish myself for awhile before making process changes was a great learning experience that I plan to take with me to all future roles.

Your comment resonates with me.

I work hard to improve things; most of it was worth it, some of it didn't went well but it was a constant fight with my boss. If I failed, he would bring it back for months.

What worked for me was to step back and get into super pasive mode. Give all the responsability to my manager. I didn't question any of his design decisions, gave support to all ideas even if seem plain wrong unless he wanted honest feedback (usually, he didn't because I would change the original idea). Never say or even insinuate "I told you this was not gonna work"; I just acted surprised and asking to him "ok, what do we do now?". It just took a few months for my manager to start reliying on me, more and more. Now I have even more space for improving things, with the full support of my manager because "he wants me to do it" not "because I push my ideas to him".

At the end of the day, it's not dumb if it works.

We've got a new member on our team (from a different team within the company) who within his first week is already trying to shake things up with "fixes"

Its driving me a little crazy. He is more senior than us, but doesn't have any of the context of why we do things the way we do

He'll explain things to us we already know, and propose solutions to us we tried months ago that didn't/don't work

After getting a little frustrated, I pulled him aside at the end of the workday and sat him down to give him some context on a lot of things on our team, but he's determined to "shake things up" and believes he's "right" so "why should it matter"?

The one good thing about this is it's taught me just how patient and restrained I can be, which is a lot more than I thought, but please, please tell me that this eventually changes?

Guys, should we tell him?

Oh, no

What am I missing?

It won't get better, he's more senior, he'll probably get promoted before you guys (and he has a head start) so he'll be your bosses boss and mandate all this stuff.

You'll leave because surely everywhere can't be this dysfunctional only to find that everywhere is then you'll reach a grudging acceptance (people will call you cynical) and you will live for your hobbies.

40 years from now a vein blows out and you shuffle of the mortal coil.

Alternatively it'll get better, he'll realise that his ideas while well intentioned are upsetting the team and he'll tone it down a bit.

Flip a coin. (I wish I was joking about the binary options but well...it'll be one of those two).

Everything changes. But it's likely to be the whippersnapper moving on (again), while the rest you you gets to mend all the semi-implemented best practices to resemble some sort of coherent whole again. Or not. Nah, you're probably ok.

> The one good thing about this is it's taught me just how patient and restrained I can be, which is a lot more than I thought, but please, please tell me that this eventually changes?

It might not, but that's not necessarily a bad thing.

Personally speaking, I've been on both sides of this conversation. A number of years ago, I joined a company and I tried to shake things up with fixes. My initial ideas lacked the context, I didn't understand the constraints, and I certainly trivialized some important aspects of what was going on. Some people were patient with me and focused on explaining the unique context and constraints. Fortunately for me, I took the time to listen to them and I was in a much better position to offer up fixes.

Some of my fixes were good and well received, and others not so much. Typically, I found my ability to create positive change was strongly correlated to me taking the time to ask people questions, heeding their warnings, leveraging their unique insights and giving their contrasting opinions credit.

When I hired a technical lead for my team, the shoe was on the other foot and when he joined. He offered a lot of very good ideas to shake things up and fix things. When he asked for permission to do these things, I made it a point to never say no, but to take the time to explain the context and constraints. His first few months weren't tremendously productive because we subjected him to the pain of the thing he was going to eventually automate. Eventually, I was given the opportunity to let him loose and give him the freedom to do what he thought was important. I'm glad we did, because he ultimately created some really good tools. More importantly, he was able to prove me wrong about some of the problems I thought were unique to us.

I guess what I learned from it was the importance of directing people's energy. As you already know, it requires the patience to continuously engage in conversations to make sure that self-drive isn't wasted. These days, I'm a lot more appreciate of someone joining the team has a strong locus of control.

If you really want him to become part of the team, try distributing the task by encouraging other team members to help him. He'll be a lot more receptive to listening to your unique constraints if it's coming from people who are trying to help him.

Hmm, well tell us the ideas and we'll tell you if he's right or not.

On the plus side, his ideas should give you a moment to reflect on whether or not the way you do things is still the right way. Sometimes you need fresh ideas and approaches. Unfortunately, it's harder to hear when forced like this.

Adam Grant talks about this in "Originals".

I'm a consultant, the biggest thing to understand is that you don't work for the company, you work for the individuals in the company. You need to immediately start solving what they think is the problem, to build the capital to solve their actual problem.

Ex. Company thinks they need more developers to ship on time (you). First, make sure you're getting tickets done and helping them with the metrics they know, then change the process to fix them for good once you have their trust.

If you skip to step 2, you've got someone angsty with a career on the line who 'isn't getting what they paid for'.

Everything here, but with an important tweak to step 1: it's impossible to know what needs fixed until you've actually gone through the motions of trying things as they are today. It's easy to come in pushing all your 'best practice', but any of it could be a bad idea in any particular scenario, and it's impossible to know without context

I don't think I've introduced anything revolutionary in the last few places I've been (going back ~2 years+), and that's also a fine outcome. Often it turns out that causing disruption to something that works well enough is far more counterproductive than simply leaving things as they are. Save the churn for a big change that really provides an important benefit, otherwise it's not worth the time

One thing that I find sorely missing in many teams is onboarding documentation. So when you come in, document everything that you need to do (required permissions, development environment setup, mailinglists, subscriptions) and how to do it.

This is a really good idea. Reminds me that I should finish up my onboarding notes and publish them internally

A good place to start, I did the same in the past.

Every new person on my teams, I have document what knowledge they are missing and what their questions are. We then fix and update the documents we have to address this. If you're on a growing team, this approach saves time/money in the long run.

This is a great way to write the onboarding docs for the person who replaces you when you get laid off

Happened to me...

We have a onboarding wiki page that has everything that's required on your first day to the day you getting your first code to master branch. We hand it to the new joinee and ask them to update it if they find something that wasn't documented. It has gone through so many reviews that in most cases that's all they require for a smooth onboarding.

It's either missing or if there's any documentation it's scattered all over the place and outdated.

I also export important bookmarks from my browser and add it to the on-boarding documentation. Links to dev/qa/prod app URLs, AWS account console pages, wiki pages, JIRA links, git repos, timesheet app, organization chart, IT support page, slack channel, project home page, etc.. just anything that a newbie to the team would need often.

Strangely, onboarding documentation does not exist in many places. I ended up creating new on-boarding doc for at least 4,5 consulting engagements and the managers appreciate that a lot.

Well, first I gotta rebuild the release process on top of nixpkgs, then, after rewriting the core product in rustlang, I can focus on replacing all the developers' macbooks with linux machines.

I already want to hire you!

I am a bit surprised all the comments so far are tech or process oriented. On my side, I try to say "Good morning" to everyone and get to know them a bit better. It allows me to quickly identify the key resource I need to get answer and being friendly usually make them reply faster.

1.Find an established religiously held standard that has little actual value (tabs vs. spaces).

2.Spend the first month gas-lighting everyone into changing to the oposite until enough people force a change in policy.

3.Survey my new kingdom with my loyal band of disciples (whilst intermittently switching between tabs and spaces to enrage the holdouts)

4.Quit

If you just arrived at a company why are you pushing to change anything. They obviously already have a working process and you should be careful to change anything that works, especially when you may not yet know all of the more hidden details.

Even if the process that they have is working it doesn't mean that it can not be improved. And if you obviously see the parts that could be improved because you already stepped on the same rake many times why not do that? Ofc as a newcomer trying to change things you are always gonna be welcomed with strange looks but that's another side of it - how to implement the changes so that everyone is happy...

More at a management level, but I have joined small commercially successful companies who had utterly dysfunctional development processes (backups? revision control? sane deployment processes?....).

I second this - there is so much to absorb when joining a new team/company. Absorb as much as you can about process in place. Ask plenty of questions. So I would suggest to setup few meetings with right people just to get thigns in place.

There are lots of useful changes you can make that don't break the world but do materially improve things. I already gave an example elsewhere of aws-vault. Similarly, CI/CD/code review are easy wins that not everyone has already. You're assuming everything is copacetic right now, but that's not a given. I doubt any startup would take the position that there's nothing left to improve. That doesn't mean you're going to start by burning the world down and starting over.

It depends on why you're brought in to the company. Especially in management it's not uncommon to hire people with the explicit notion that they don't have a satisfactory working process, it needs significant changes to achieve the desired results, and the new hire would be expected to start fixing the current process almost immediately.

I would argue that even then you need to assess before making changes. If you're brought on for your expertise in process, you need to trust your own judgment on where the problems lie. Whoever is hiring you may have a sense that something is wrong, and may even have areas they think are broken, but if you're brought in as the expert, you should assess for yourself.

I once joined a company and found out on day 1 that they had:

1. No source control system

2. No bug/issue tracker (or formal software QA)

3. No build automation

4. No dedicated build system

5. No pre-launch checklists

Basically, the latest release was whatever happened to be on one of the engineer's hard drives whenever someone frantically ran in and said "we needed to release!" You can imagine how fun it was to repro when customers reported bugs. And they did, Gandalf, they DID...

Those were the first things to address because they were obvious gaping wounds and I could implement them myself without really having to convince anyone. The CEO thought they were a waste of my time (I hired you to write codes) but didn't actually stop me from setting them up. The next things lacking would take more effort to fix because they were people/process dependent: like no code reviews, no software development process, no bug triage process, etc.

How long did you last? I worked somewhere like that, most engineers lasted 3 months, I managed to squeeze out 4!

Places with issues like that tend to have TONS of other very serious issues.

You guessed right. Turnover was a huge problem too. I lasted just over a year, and only because it was during the depth of dot.com recession 2.0 and there weren’t exactly jobs available on every street corner.

The technical problems were merely symptoms of structural and leadership problems.

Basically you just described the situation at my first workplace in 2007. To be fair it wasn't a software company, and most of the software was for internal use. Still. The first proper installation of SVN happened only in 2010...

That is still the issues in some of the projects that I work in.

Team not knowing any version control properly is one of the most common issue that I find. Nobody knows about unit tests. Build systems and checklists would be something too alien to comprehend.

First day I find the best dev and kick his ass. Gotta set the tone.

This is such a great thread.

No it's not. Please don't turn HN into a joking competition. There are other websites for that.

Jokes are fine IMO, low effort referential "jokes" are the problem

Pee on their desk. Establish territorial dominance.

Make sure to get a MX Blue mechanical keyboard, so that everyone is aware of who's doing most of the keyboard mashing around the office.

Cherry switches? Millennial... You really need an old IBM, plus it doubles as a weapon if your dominance displays backfire.

My first pro gig was on an RS600 workstation. I miss that keyboard.

Old article but gives me a laugh every time.

https://medium.com/feature-creep/the-software-engineer-s-gui...

I'm a product manager, so I'll vary a bit from the development-specific things already listed. Basically, when I get a new product line (or company), it goes the same way:

1. Gather hate mail. Find whatever complaints you can about the product and team you've just inherited.

2. Use the product. Try and break it. Act like an angry QA engineer.

3. Find the person or people who support customers on the product. Ask them what makes their job suck. Ask what's broken.

4. Ask them why they think it sucks / is broken - preferably outside the office (coffee, lunch, etc).

5. Meet dev team. Ask them why the product matters. Gauge their interest and understanding of the problem and customers. Ask what they think is important to address as a team.

6. Combine answers to 3-5, identify common threads. Look for places where there are common blocking factors (cost, time, focus, politics, history).

7. Find something to work on with the team, that can be delivered fast. Talk about what you want to do with support folks (from q3). Sanity check, make sure dev team understands the value of what they are working on.

8. Check in with superiors. Make sure you understand what's important to them. Talk about what you've heard.

I've found I can't come in and expect to be an expert in a given area overnight. But I can be good at asking questions and spotting painful things.

(edit: formatting)

Hahaha! Good lord. First I push for a DEBUGGER. Second I demand they test their backups. An untested backup is just a delightful wish.

After months of push back for those two and I've made myself a hateful person to all involved I ask for ALL code to go into repos. Often there is a bunch of "Oh, my code doesn't need to go in, for reasons." No FUCKING NO, your code needs to go into a repo and needs reviewing.

The boss needs all passwords. Okay, not your personal passwords, but if you're not in and you're sys-admin, we need to get into the f-ing box. You can not be the only person with a login. Create more users, give those users permissions. So many companies have one guy/gall who has access to some critical part of the puzzle and no one else knows how to even log into it, let alone all the hacky scripts that are needed to push a change live.

Automatic testing. We almost got there in one company. So close... until one day they ran out of money. We found that an SQL statement wasn't coded right and we hadn't billed 50% of our customers. Ever. No a dime. Not a cent. Accounts never realised. Even in the early days when they only had ten or so customers. The billing record shows they only sent four bills out. Come on people.

I find it helpful to have a "misc" repo just for those weird not-quite-one-off scripts and the like that don't really fit into the main repos.

>> For the first month or so I take a very humble listening position

.. and then

  - Everything in source control
  - CI
  - Static code analysis
  - Artifact repository
  - Automated deployments, incl database and configs
  - Branching strategy & pull requests
  - Standalone dev env per developer

What do you use for an artifact repository? I’m assuming you mean the cached artifacts of builds, but also vendor artifacts/cache like npm_modules or docker containers?

This sort of vendor dependency management is a problem I haven’t found a great solution for yet. I’m actually thinking about creating a product that’s implemented as a proxy and supports multiple package managers, including docker, and caches all downloads keyed by branch. This way in the event of some catastrophic dependency failure you have a place to find the last working set of vendor dependencies that didn’t break the build.

Would anyone be interested in this? What is current best practice for this workflow?

One popular option: https://jfrog.com/artifactory/

This is not technical, but I always push for monthly performance reviews, with clear goals, and a weekly dedicated time to check in with a manager once a month to make sure I am spending my time on the right things. It doesn't always happen, but my experience has been the harder it is to get these things the less likely I will feel productive.

Latacora perspective, AWS specifically: go install aws-vault. https://github.com/99designs/aws-vault

There are a ton of benefits to aws-vault. Strategically: getting everyone on an aws-vault workflow is step one to eventually making your IAM story great. We'll be publishing some general stuff about how we think you should start cleaning up your IAM story. We have Strong Opinions(TM) on how to get you from "bunch of people have * : * perms with keys they have on disk" to best-in-class, BeyondCorp-compliant temporary perms acquired on trustworthy endpoints.

(FWIW: also undersigned re: start by listening. Latacora starts with an audit too, but that feels like a cop-out answer :))

Oops. I was thinking of the wrong tool. Personally, my biggest peeve with temporary IAM credentials is the duration. Having them invalidate in the middle of a Packer build is a real mood killer. Our own company got them extended to 12 hours recently, which was a huge win in this department.

Original content - about Secrets Manager:

AWS Secrets Manager is stupidly expensive for a password manager that rotates passwords. It can't even rotate all passwords, just those for a specific subset of AWS services.

Should instead start with parameter store (which is free but still offers encrypted password storage) and then figure out what parts really need a rotating password and that are operating with services which Vault can rotate passwords for - at which point you migrate only those.

You appear to be confusing aws-vault, a gratis and open source project that manages IAM credentials, with AWS Secrets Manager, a hosted AWS service that stores and manages secrets.

I agree AWS Secrets Manager is overpriced but I doubt it's a major expenditure for anyone. You should probably just use KMS instead and dump the ciphertexts wherever you want. Parameter Store is a fine place for them.

I did. Clearing up.

That said, it is a major expenditure when used as part of the automatic workflow. And parameter store has KMS encryption/decryption built-in. Alongside full IAM level isolation.

So, concretely: $0.40/secret/month (prorated if < 1m) + $0.05 per 10,000 API calls. KMS: $1/CMK/mo + $0.03 per 10,000 requests.

What are you doing with it that makes it a major expenditure? That seems like a drop in the bucket compared to anyone's compute. Are you dumping 500 secrets in it?

We were looking at it for a configuration management backend. So, yes, 500+ values, consumed by microservices.

I still say - the only real value even when compared to other AWS services is the rotation, which currently only really works with DBs (and then only if your service connects to the Secrets Manager directly, with every DB open).

Yep, definitely not debating that it's overpriced and questionable value compared to KMS + storage of your choosing -- just surprised that you ended up with a model where it's nontrivial cost :)

Just a note on Secrets Manager which you probably know, but is worth mentioning just in case:

Secrets Manager charges per Secret, but if you are storing non AWS values (API keys), then you can put several secret values in one Secret. Not sure if your 500 values number was 500 Secrets, or 500 secret values which could perhaps be grouped logically together into a smaller number?

Replying to new content: it's true that Hashicorp tools in particular are hilariously bad at dealing with expired credentials. Terraform doesn't realize the error and just sits there banging away (retrying) forever.

If this is really a problem (that is, you reliably need more than 1h of role time and you can't get AWS to extend your duration for you), aws-vault knows how to mimic the metadata API. This resolves the issue, since it will transparently get new credentials for you.

I often walk through the Joel Test with sharply declining urgency ...

That is I more or less demand source control, work on automated builds/tests (on each commit, not daily), start to log everything I see in JIRA (or another tracker), Look for an up to date schedule (ie, discern business priorities and timelines), attempt to start specifying how future things ought to work, train my coworkers to see when I'm wearing earplugs to drown out their non work related chatter....

https://www.joelonsoftware.com/2000/08/09/the-joel-test-12-s...

I try to understand what the real problems are, and if there is the will to fix them. Then I try to understand the real social hierarchy and everyone's biases.

In the last two jobs I've started, both had serious problems from using an ORM framework and dependency injection framework incorrectly. In one company, the project ended up going nowhere because of incorrect biases towards using a database. In the other company, everyone knew that if they didn't fix the problem, they'd go out of business.

I left the company that didn't want to fix its code, and still work at the company that fixed its ORM and dependency injection problems.

[Edit] The project that went nowhere failed because the lead programmers didn't know how to use a database. They wrapped it with layers of frameworks and code generators. The layers took so much time to work with that the schedule dragged out, and we missed our market opportunity. There was no will to fix the real problems, so ultimately I knew I had no future at the company.

The first thing I do is work to gain enough political leverage so that I can manage my own time.

Can you give an example of how you’d do this?

Unnamed envelopes left on people's desks?

In the broadest sense, by gaining the trust of people and by showing initiative, rather than waiting for someone else to dictate what I should be working on.

Sounds like a nasty place to be in if the first time you do is politically based.

It's a hard lesson, but everything in a company is driven by politics. Technical skills will only get you so far - maybe to the senior individual contributor position. Beyond that, your job will include communication, evangalization, and compromise.

I realise the way I put it may sound ominous, but it's for the good of everyone involved really.

Most organisations are shockingly ineffective. Micromanagement and lack of long term planning is abundant. I get hired because I'm good at writing software. This is not wrong, but I can add much more value if I deliver what is needed rather than what is asked. My goal is simply to be able to do that.

Could you share a longer description of how do you do it?

I'm afraid I'm not deliberate enough to have an actual playbook I go by. It's more like; this is my goal for the first month or two.

To what extent? Up to days? Weeks? Months?

Would you oppose daily standups?

"Daily standups" are morale killers.

Daily standups for remote workers are godsend. You'd think you could rely on people to communicate over chat or email, but the standup actually gets everyone talking and discussing.

Perhaps. But do they really need to be daily? Maybe 2 or 3x a week.

Having tried all three, every day built a lot more comradery than 2-3x per week. It also helps the remote workers feel more in touch with what's going on.

My current team does weekly, and two of us are remote. Our half hour meeting invariably runs over an hour, up to two hours. If we did it daily, we could keep it to the cap without really taking more time.

Indeed; I saw the same problem. Our team (4 out of 8 are remote) does daily meetings now, and it's actually pretty rare that we go over 10 minutes, let alone the scheduled 30.

Would you mind expanding on this? I'm interested how your experience with them differs from mine.

Generally people are incapable of communicating efficiently. A standup should cover: 1) what did you do yesterday 2) what are you doing today 3) do you have an issues?

This should take less than one minute per person. "Issues" should be resolved offline.

I once worked on a team where the "scrum master" would update Jira for each person's status. This resulted in a 30 second update turning into 2 or 3 minutes of detailed status.

I also worked on a 15 person team that had a giant stand up for the entire team. The resulted in a 30 to 45 minute stand up.

Sure, those are bad. That doesn't mean standups are bad though. One thing I found successful was to push for the standup to start 15 minutes before lunch. That gives ample time for the standup (2-3 minutes per person is longer than one should need, but my team likes to take notes during the standup, which while lightweight does delay things a bit) and a bit of followup, and deciding where to eat.

Also doing it just before lunch means everyone is in the office, you aren't breaking anyone out of flow unnecessarily, and everyone has a decent idea of what they will actually be working on today (since they are already in the context), so you don't have the issue of "hmm I don't remember what I was doing" or "uhhhh....oh right I'm planning to work on X" delaying things.

One of the first things I do, as a sysadmin/devops person, is to look at how "easy" it is to communicate.

In other words, does this department have group chat, how easy is it to add documentation, how do I tell who is on call, am I being told things face to face or am I being walked through existing documentation?

This is related to a lot of deep issues in operations or development, I feel. If the only documentation is fire and forget word documents in a windows shared drive, does anyone read them? Can I search for the information I need?

Is the department ruled by one or two people who hold all the knowledge? Are all decisions made by those people, or are there people who never read emails and always demand face to face meetings to discuss issues?

Communication is key. What you do and how you do it follows on from how, what, why information is shared.

How do you improve communication issues when you discover them?

For example suppose you encounter documentation by word documents in windows shared drive and an set up but not really used confluence (so we don't need to think in this example about setting up a system technically, but how to make people use it).

I think the first thing you should implement is your own understanding of the current codebase and processes. I have seen it now several times that new guys come in and immediately push for their pet architecture without even trying to consider that we are not complete dummies and a lot of things are there for a reason or are at least not that easy to change. Usually it ends with them being rejected and then getting frustrated because they didn't get their way.

On the other hand we also have people come in, help with the current codebase and after a while they make proposals for improvement that are based in reality. These people integrate well and are quickly respected team members.

Linting and code style guidelines. Easy to introduce, but makes a big positive difference.

In that vein, I invariably have one massive commit on every project to remove trailing whitespace first. That way when my well-behaved editor removes them with each commit, it's not littering up the diff.

Frankly, I saw this in a few projects and it feels like the responsible is one of those people that can't actually code but wants to convince management of their impact with their huge commit stats.

I also hate whitespace but it's just a symptom (the other developers' editors / git config probably don't show the trailing whitespace).

Given this, it's a mere symptomatic remedy, the problem will reappear, and the only person benefiting from this is you. I'd hate to pay you for that.

For what? 30 seconds of writing a sed command in the shell? I can donate that kind of time to the project for free, really.

I think the process would include having the team become aware of the situation and improving their editor configuration to stop littering whitespace everywhere. Otherwise I agree, that seems like a waste of time to do in isolation.

I'd probably address it more completely if so many files are going to be touched, and whitespace is only one symptom of bad formatting connections. Perhaps everyone should employ the same formatter on save, for example. There is far more value in that. Getting rid of only superfluous whitespace is a bit of a time sink for what you get in return (as much as it drives me nuts).

My opinion is that every team member should have the same editor with the same settings. The settings should be easily accessible from Confluence or a similar knowledge base.

Agreed, it should be part of the standard technical on-boarding process. Once someone is familiar with what the editor is buying them in terms of productivity they are free to search for their own should they choose. A pet peeve of mine is joining a new team and asking what the editor of choice is to be told "really it is up to you."

what's the point of that?

it takes a while to learn how to use your text editor well, and everyone is probably good at a different one. but they all pretty well have the ability to produce the same result, so why bother forcing one?

it's better to (have a tool that can) specify what the end result should look like and let people work the way that they are good at.

Agreed. Plus now many editors obey the same .editorconfig files; and for those that don't, .editorconfig can be used as a reference for developers to configure their own working environment.

I can understand wanting to standardize in a company with a 1000-person engineering org, where maybe it's harder to enforce that everyone uses the same conventions if there's no standardization in tools; but in a team of a few dozen, you should only be hiring people you trust anyway, and communicating with them about why small things like this are important.

In my team everyone uses IntelliJ Ultimate with the same settings.xml file. We all have the same automatic tasks that happen on each commit: reformat code, optimize imports, check TODOs, perform SonarLint analysis. This has greatly reduced frustrated merge-requests filled with unimportant details such as code formatting and newlines. It has also greatly improved the code quality because it will warn you that you left a TODO in the code or that a certain method could also be private before you commit the code into the repo.

Nobody has a problem with this, although in the Java world every corporate developer uses IntelliJ anyway. A couple of legacy project teams are still on Eclipse.

As long as everyone has the same linters, what does it matter what editors they use?

I can see why everyone should use the same settings, but am not sure why everyone should use the same editor.

An easy way to sync formatting: https://editorconfig.org/

This will pretty much guarantee a decrease in productivity, as opposed to the original intention to increase productivity. Why can't everyone use their own editor? Enforce standards, not tools. Something like editorconfig (I use it in pretty much every large project I have) solves this for you.

That's going to improve the overall productivity of the worst (maybe) devs while hurting the productivity of the best ones. For the latter, it took years to get to the level of proficiency they are on now with their editor, and they are not going to be as productive in the new one for a long time[1]. You're intentionally crippling them by taking their tool away - why would you do this? Why do you expect they'll put up with it?

[1] And that's assuming your chosen editor is objectively comparable in features with the one they used, which it probably isn't unless it's the one extensible in Lisp ;)

If you're pair programming, you should absolutely do this. It's a substantial impediment to equal contribution if you don't.

If you're not pairing, it seems like a move with a poor payoff for its cost. Sure, make sure everyone has identical code style in their auto-formatter, but let them pick their own editor.

Change the settings in your editor? These sort of commits change the history in favor of the OCD-whitespace person, make "git-blame" a pain and generally look as if someone is trying to increase his line count.

I did this at my current / new assignment, turned out eslint was running but it was skipping tests, and it ran over the dist folder (e.g. minified code), annnd it didn't run with the --cache flag. Brought the runtime down from ??? (didn't wait for it to finish) to 30s to 2-3s, and it made thousands of minor inconsistency fixes. It was appreciated, thankfully, :p.

It depends on the project. The biggest thing is to assess where the team is at. I just left a project where the team had serious issues and the leadership did not have the desire to fix it...IE: a tech lead that was more of a mid level dev running a command and control style thing. The team, with more experience, did not have a say in the architecture, what they got to work on etc.. All devs had to get their commits past the mid-level lead, the lead would reserve most of the fun and hard stuff for themselves and leave the scraps for the rest of the team. The lead had multiple silo'ed efforts and, as a result, had a higher number of commits etc. on code base partially because they were constantly declining PR's from the rest of the team to do it their way.

Now if you have a team that is actually open to your ideas things are VERY different. I've worked on them and they are amazing. The key thing is to evaluate where they are at and apply what is going to work for them. The biggest thing is to avoid the one size fits all approach.

With the original comment for this thread, my biggest issue out that gate with their approach is that you are using a lot of branches which negates the benefits of CI etc.. Why not instead try to figure out how to reduce branches and have more people checking in working code to dev with unit tests?

(front end js)

My new favorite tool is the ridiculously named husky package, which allows for configurable git hooks inside of package.json. Specifically what I'm doing now is precommit eslint and prettier, and prepush test:all i.e. people on my team will be unable to commit if they fail lint and unable to push if they fail unit tests. There's of course positives and negatives to this approach but the former significantly outweigh the later in my experience.

And you do this in a new job? Introducing a linter the first week seems like a great way to make your new coworkers hate you. Sure, it's a good thing to do, but if your teammates aren't already using one then unilaterally introducing this into the commit process seems a little radical.

My OP should have called out that I specifically let everyone know that I have no problem with them using git commit -n and git push --no-verify to get around it if they are in feature branches. But yes I implemented this on day.. 2 of my current position which was lead of a greenfield project.

I've considered this because I love the idea. I just assume I'd start seeing tons of skipped tests, haha. "I'll fix that later".

This completely breaks a number of git workflows. In my opinion a better option is to have eslint / tests / prettier / etc run as part of CI, and have your pull requests require CI to pass before they can be merged.

I like this balance better because the end goal is still met: "bad" code doesn't make it to the main git branch.

But it also allows for git workflows which involve frequent commits. (If all tests have to pass for every commit, even locally when the commits may be rebased away, it encourages very large and hard to review commits instead of the smallest commit possible for the given changes.)

I job-hop a lot in corporate environments (mostly Fortune 100), doing DevOps for legacy systems/teams rather than coding. As such, I don't push for anything when I first arrive.

It can take a while to understand how all the moving parts interact, both technically and organizationally. The systems in question are sometimes responsible for tens or even hundreds of millions of dollars in business, and critical corporate functions. Wading in with "Hey, I know more than you, stop doing that and do this instead" is the short path to sudden emergency downtime for production systems! And that's knowing they hired me because I'm the expert and know more than them.

So there will be processes that are really, really stupid. Slow, inefficient, maybe completely dysfunctional. But if they work, they work. Fixing/replacing them means interactions with other processes that can be very difficult to pull off. Process is usually a Big Ball of Mud Antipattern at the point I'm brought in, and fixing anything in the Big Ball of Mud is a challenge.

As for legacy apps... yes, built with antiquated technology, often poorly implemented, with a lot of uncertainty and fear. Change is really scary. What to do about this stuff depends on what the long-term vision for the product is. Is it in maintenance mode, or under active development? Is there a plan to replace it? Is there a realistic plan to replace it that has working results and a viable schedule? Generally, the best thing to do is leave the scary ugly thing alone. It was probably done pretty well back in its day.

Where I usually find myself making progress early on is finding things that are broken due to communication problems. One team says one thing, the other team says another, and everyone is mad and nothing gets done. Often, it's just a matter of rephrasing things to both teams, to find common ground and a way forward that everyone wants.

So really, my expertise isn't cool tech. It's being a good communicator on the engineering rather than the management side, someone with both development and operations experience who can speak to the concerns of both sides, and has seen similar problems in other organizations (big organizations like these usually have 10+ year people in key positions, who have no idea how the rest of the industry works anymore).

So yeah, the first thing I push for? Learning the lay of the land, so I can start charting paths.

FeatureFlags for sure. They don’t force anyone to change their day to day but allow them to adopt better practices at their own speed.

The very first thing I do is update documentation.

You're a fresh set of eyes and so documentation for onboarding, setup, and building the application on your laptop is the kind of thing that often goes by the waist side.

Did a step not work because you've updated your OS? Was there a critical typo in the terminal? These things provide immediate value to all future hires.

...by the wayside

A Docker or Vagrant setup to match their prod as closely as possible, for local dev purposes.
It boggles my mind how many developers _still_ install PHP/MySQL/Ruby/Node/etc on their daily desktop and are surprised when something doesn't work as expected on production.

Do you typically choose one over the other?

I'm not them, but for me I would use Docker if I am tearing the stack up more than a dozen times a day, and Vagrant if I am doing it less.
I doubt I use either of them correctly. But I do love the way I use them.

Same. I generally try Docker first. With multi-stage builds, you can reduce container build times by a lot (after your first build), as opposed to reprovisioning an entire vm every time you need to nuke your dev environment and start from a fresh image.

It war rare to find places with automated build. My first priority was always to get humans out of the equation because as a contractor you need to trust the pipeline and you need to be sure whether your code hit production or not since it’s critical in issue management.

Proper (as in working and recoverable..tested to be recoverable under the worst case I could think off) backups.
I wish I was kidding but the last 'complete' back up they had was from mid-2014 (and the system was still in initial development from 2013 late 2016), I started June 2017.
Outsourced development company (and bad developers and..well stuff I'd never seen before, RAID on the server but only 1 disk in use, 64bit Xeon's running 32bit Debian...and on and on it went - A backup server that had nothing on it..I mean literally nothing, the entire system runs as root (because the way to solve your inability to understanding the linux permission model is just to run everything as root apparently).

The first thing I do is fix bugs. It lets me know the types of problems that come up.

Abolish overbearing dress code, if one exists. Social/lunch outing on Fridays.

Internal URL shortener, every single time. They get rave reviews and in one case ended up being considered a core service that had to be up.

Can you explain what the purpose/benefit of this is?

It turns a mess of internal sharepoint/wiki/confluence links into an easily memorable namespace that can be 'linked to' verbally or on post-it notes.
A common hostname is 'go', so when you launch some new programme, project or tool, you can put 'go/projectname', or 'go/toolname' in places like chat topics, email footers and presentation slides.
Applicable in larger places that end up with a mess of different documentation systems, and where trying to unify everything would be a waste of time.

Spend time talking to people, learning what the hard and hairy problems are. Playing with product and getting a feel for what customers experience. Dabbling in code, trying to make a mental architectural map and asking coworkers to validate assumptions. “What happens when someone does X?” questions.
First week is lots and lots of asking noob questions and documenting them if it’s not already done.

Mandatory learning something related to the work. Either the company schedule professional classes for that or reimburse the equivalent amount of money if you self-learn.
Assuming your employees to know everything and not let then learn is a path to your organization's downfall.
Ben Horowitz makes a good case about it in his book The Hard Things About Hard Things

CI/CD. Revision Control. Artifactory. VPN.

VPN?? For what?

Not parent, but generally to be able to do remote work.
Production goes down and you're not at the office (1h travel)? Now even a 1min fix will cause 1h + 1min of downtime.

So is your cloud in the office then?

The cloud can also be on a VPN.

Update the codebase to Python 3.6.

F-strings alone make the upgrade worth it.

What's three amigos? Never heard that term in programming.

I had to google that as well. It seems to be an agile practice [0] that consist in gathering a developer, a product owner and a QA tester in order to produce acceptance tests using the format given/when/then.
[0] http://jonkruger.com/blog/2012/01/04/the-three-amigos/

Nice. I suppose the code is the singing bush then. And the end user is the invisible swordsman [1].
[1] https://www.youtube.com/watch?v=e9vPvHO8Kp4

Who came up with that, given that "three amigos" is a pretty well-known term for Booch, Rumbaugh and Jacobson?

Documentation is my biggest thing. I start with onboarding, CI/CD. Then start adding api and archicture documentation. This forces me to learn, and ensure I digest well enough to explain to other people.
Once that's done I start adding unit tests, monitoring, and additional dashboards.

Documentation has some great properties as something to work on in early days (so long as you aren't immediately firefighting).
* Documentation always sucks, no-one wants to do it, and everyone knows it has room for improvement. It shows you're willing to roll your sleeves up and do the less glamorous stuff.
* Working on it prompts you to ask simple questions so is a good way to get to know people on the team, and in the process learn the history of the team, why things are the way they are, and where the dark corners are.
* You're immediately creating value, rather than doing bugfixes no-one cares about or having meetings about things which are months away from fruition, and demonstrates you're here to make things better for everyone.

Joining a new company is like starting a new life, which doesn't seem to happen many times in a life time. It is like you are being given another opportunity to start fresh. First thing then to do is gain respect, learn the culture. It is going to be uncomfortable for a while, so it is important to keep the opinions under check. Let the actions speak more than words. Remember that every design issue is a choice made by someone else to the best of their abilities. Finding a way to move forward without making too much splash automatically unlocks the doors. There will be lot of things to implement and you will find a way and while doing so you will learn a lot.

Latacora, corpsec perspective: audit Google Groups and OAuth'd apps, run a phishing red-team exercise.
Finding appsec bugs matters but maybe not so much if everyone just signs over whatever privilege apps ask for and it'll exfil whatever's on Drive.

Single Sign on.
There is nothing worse than loads of different accounts that are all for the same person.

Bonus points if the multitude of accounts don't map 1-1 to people. Sometimes an account is for a user, sometimes it's for a team, sometimes it was a user until they quit and it became a team account but still with the original employee's name. The accounts are all individually managed, of course, so getting access to something requires raising a ticket to the relevant team, then testing whether the account they gave you actually has permissions to do your job. But sometimes you find that they only gave you read-only access because only they can actually modify that cluster. Oh, and sometimes you find that an ex-employee only had maybe half of their accounts deactivated, and one of them has been recently used, and you have to find out whether you're looking at a security breach or just "recycled" account use.
We use SSO now. It's nice.

I start creating a glossary of all of the unique and important terms and concepts used by my team. This is a great way to confirm understanding and becomes great documentation for the next person to join.

Wiki - confluence has a nice flat cloud offer for $10/mo for up to 10 users. Not only for tech people, but also for non-techs: marketing, sales, office people. And you can connect it to jira.

Document things to get an idea what's going on. Add comments and probably tests (but don't rewrite) to the 2 page function to see if you understand the style of the previous developers.

$3500+ for business travel UK/USA vs $800 for economy. I always get companies to offer the employee half the difference to fly cheap. Win Win!

I’m a consultant. Honestly, I identity a good source of decent coffee, even if it means packing some at home. A reasonably comfortable chair. And if the temp is out of my comfort zone, I’ll pick up a desk fan.
Making sure my creature comforts are in place helps ensure my productivity. Also, on my way out I ask the most helpful person if they’d like the fan and leave it with them. A calling card of sorts.

I am usually new to the business domain, ergo, I start compiling a "Dummy's Guide to [Plant Genetics]" or whatnot. The code and the tools used to work on the problem domain are always changing, but the basics of the business usually are not. My guides help new hires understand why the business does what it does so they can start adding value more quickly.

I mostly do ops rather than dev, but:
First, is anything broken? Any RAID arrays that are degraded or failed (yes, I've come into shops where that was the case). That sort of thing.
Are systems secure? Are updates applied? What sort of network security is there? If there are known holes, has anyone compromised the system?
Monitoring, how do we know something is having problems before the phone starts ringing?

as a job hopper and " contractor" unless you have been explicitly brought in to set up better processes id STFU.

Lead developer here, commonly brought in to overtake projects. Proper workflow for the team is the most important thing: make sure that each team member has an easy and unintrusive algorithm or picking small tasks, completing them and relaying them to the next one responsible makes team morale and planning a lot easier.

A eslint-config for the team!
I get that setup with a style guide during the down time of the allotted "onboarding" phase.

CodeClimate is a big one for me. Having some static analysis to track the team's progress over time is huge. It's nice to have a neutral third party robot doing the complaining about poor code.
Fortunately, CI/CD seems to be pretty prevalent these days. But if it's not in place, that's always first.

Implement or fix basic integration testing infrastructure. It is usually broken or doesn't exist.

I usually take a humble attitude as I pace myself into things and blend with the team, but the first thing I try to take care of is make sure the Joel Test is passed. It's amazing so many shops and companies seem content with a score of 2 or 3.

I always test the backup restore process. It's amazing how many times you find issues.

Delete as many things as possible without breaking anything. Lots of crap tends to build up and nobody wants to keep lugging around several hundred megabytes of useless auto generated build garbage.

CI. Code analysis. Revision control. Something for documentation.

I work on Ruby 95% of the time. If there's no well-configured Rubocop setup, I get that into place as my first order of business almost immediately.

> a good feature-branch flow
Ain't no such animal.
https://trunkbaseddevelopment.com/

Trunk based development is a feature branch flow.
What do you think your local copy logically is?

The first thing I want to see is a culture where people listen to others and understand where everyone is coming from before pushing their own agendas.

static code analysis e.g. Sonarqube.
CI/CD

I connect to the mainframe and then execute variables on the system. This gives me access to data I would otherwise not have.

Mainframe? Sounds like back in the 80s or 90s :)

Like the post about overbearing dress code. Perhaps some irony. Or time-traveling posts..

if there are smokers, join their breaks. it's a good way to learn about culture, history and customs of a team.

I request good ergonomic equipment so I don't needlessly work in pain. Otherwise I'm pretty flexible.

Lately I've been adding prettier.io to all the new projects I join. Great helping tool :)

Proper logging, if they don't have it. Otherwise, take a hard bug and fix it.

Do you know any resources for learning this?

Any open source project with open bugs (that's most of them).
Proper logging: that's a complex subject and it took me a good chunk of my career to figure that out.

Company funded Friday lunch.

with opportunity for employees to pick their own lunches.

#tl;dr
Regardless of how long you stay with a company/team always leave it better than you found it. Requirements Gathering, Paper Prototype, MVP, UX-testing, Docs, Tests, Linting, Static Analysis, Git/GitHub Workflow, Team/Personal Learning, Code Quality, CI/CD, Pipelines.
#longform
Assuming the company is new to me but has already been writing/shipping code for before I arrive ...
I ask clarifying questions to get "up-to-speed":
1. What is the Problem? - Understand what problem they are trying to solve, do users actually realise they have the problem or is it a case of "build it and they will come"...? (it's vital to know why we are building something to avoid wasting lots of time on something people don't want! see: Bill Gross "Why Startups Succeed": https://www.ted.com/talks/bill_gross_the_single_biggest_reas... or Paul Graham "Make something people want": http://www.paulgraham.com/good.html A "red flag" is when there are no clear "personas" for prospective users. see: https://www.interaction-design.org/literature/article/person...
2. Workflow? - Is there an existing clear "workflow" for collecting requirements, defining user stories and getting the features built and UX-tested? or is it all verbal between "founders" and the one dev? (comes back to how old/new the company is; is it a brand new "startup"...?)
3. MVP Defined? - What "MVP" has already been shipped? who built it? what tech was used? was the work "outsourced" e.g: to remote contractors or an "agency"? was a revision control system used e.g: GitHub? If no MVP has been shipped, is it at least clearly defined in the backlog?
3.a Paper Prototype?: what is the minimum you can do to test an idea? See: "Google Ventures Design Sprint": http://www.gv.com/sprint & https://youtu.be/Z8MOwcqZuuU
4. Technology & Tool Selection - If the personas & problem is well defined, and minimum features captured in a "backlog", then we can discuss technology choices. It's essential to have these choices documented somewhere, because this question will come up in the future and "because it's popular" on https://stackshare.io is not a good reason for selecting a tech/tool; whereas "it was the best choice for our specific problem/domain" is a good reason to choose a tech/tool e.g: https://github.com/dwyl/technology-stack For example: if you're building a robust real-time messaging system, use Elixir/Erlang every time. If it's just a "low budget quick-to-market" MVP to get a demo out to start testing and get "funding", use Meteor: https://www.meteor.com (and accept the "technical debt"!)
5. Developer Workflow
- Documentation Driven Development: If it's not already being done, focus on this first, without clear docs for the work done, "you're going to have a bad time" when trying to understand (never mind "fix") things in production.
- Test Driven Development: If tests aren't already being written, understand why and fix it. Should you follow ("strict") "Test First Development"? Or is it "OK" to write tests after the code? The answer is simple: if you want to write less code that is more reliable, learn how to (and discipline yourself/team) to write the tests first! see: https://github.com/dwyl/learn-tdd If you're stuck writing the tests for a feature/idea ask for help till it becomes natural!
- Pre-commit Hooks: Make the tests, "linting" and doc checks run on the developers localhost before they can commit. See: https://github.com/dwyl/learn-pre-commit If your tests "take too long to run" don't use it as an excuse to disable the pre-commit, fix it! Having slow tests (and build process in general) is a cancer that will gradually "sap" the productivity & energy of the team! Analogy: it's much more difficult to get physically fit if you are an obese "couch-potato" than if you simply maintain your fitness each day; "Unfit" Apps die young.
- Code Analysis: If there is an automated tool for your chosen tech/tool/stack use it! Even if costs money, think of it as "member of the team" not an "expense". It will always save you time in the long run.
- Continuous Integration: Pick a CI system based on your tech/tools and implement it for your app. it only takes a few minutes: https://github.com/dwyl/learn-travis
- Code Review: Use GitHub Pull Requests (or the equivalent on BitBucket, GitLab, etc.) and leave helpful comments, besides pair-programming this is one of the best ways to learn as a team.
- Continuous Delivery: When Pull Requests are merged, they should be automatically deployed! If the app/product/company is new, use Heroku for deploying your app! Don't waste time on DevOps till you need to! Migrating to AWS or GCP is easy once you have "traction" (i.e. if you're paying Heroku $200/month, you can justify orchestrating/managing you own DevOps/Infra). see: https://github.com/dwyl/learn-heroku
- Continuous User Testing: Ensure there is a clear process for testing the new features you are releasing. Ideally "get out of the building" and test with "real users" in person. see: https://steveblank.com/2010/03/11/teaching-entrepreneurship-... "weekly" should be the minimum user-testing cycle. No "excuses" to not test! Use online services like https://www.usertesting.com if you aren't physically near to your users.
- Continuous & Validated Learning: Instil the habit/culture/expectation that everyone should keep learning. If people "stagnate" everyone suffers. The Product will be worse, the best people will get jaded and leave. Learning is easy to forget but it's just as easy to maintain, it's just a question of routine.

Thanks, I'm going to implement these in my company.

CI/CD
Dockerize all the things

Where do you stop short? I'm conflicted. I sometimes look at Docker and am like "this is great", but I also sometimes look at a plethora of Dockerfiles and I'm like... what are we doing wrong? Do you, for instance, Dockerize small Python tools (or similar)? How well does this work?
I remember one project where we had tons of small Pipenv projects and one pain was that a few were Python 3.5 and a few others were Python 3.6. I guess Dockerizing these would have mitigated the pain but honestly I am a complete Docker n00b and wouldn't know how to go about setting this up in a way that wouldn't cause more pain and another layer of abstraction.
Any tips? Reference material, etc?

> we had tons of small Pipenv projects and one pain was that a few were Python 3.5 and a few others were Python 3.6
Isn't pipenv supposed to take care of that? You pipenv run the tool and it's automatically executed in the right virtual environment.

You can't set it up without the Python binary you want already being on the machine which may be a hassle if you are chasing "latest" and you have machines in your ecosystem that run old stuff, for instance, Jenkins nodes.

You'd have to combine it with pyenv to allow for multiple interpreters and automatic switching between them.

Fraud prevention, gate keepers.

The first thing I implement at a new company is configuration management using OS packaging.

Auth. If you can stomach it, back it up with a real directory service. JumpCloud is a great way to do it. It's free up to 10 users. You can use it with Google Hosted Apps as your user backend. You can set it up in 10 minutes. It has TONS of features, you probably won't look at them all once you can use it as an SSO/LDAP provider, you can forget about all that until you need more. Also you can easily replace it with something self hosted if you grow to the point of needing to do something else.
Determine if you need organization level RBAC (Role Based Access Control). Does your app need to have account managers at the customer level? You probably know from the outset if you'll face this problem. It's a big pain if you get someone to implement your product somewhere, then they lose that person and they have trouble accessing their account. Not that you can't provide support to solve it, but the legal side can get tricky and no matter what you lose face with the customer over the frustration. DockerHub messed this up IMO and that's why they haven't added it, because it's too complicated to add now.
You can easily have a simple SSO layer on top of it so your super admins come from the LDAP(or other) and user/customers are a separate DB in your existing app. It can be really expensive to add complex auth or change how it works later, but a stitch in time makes it easy to grow and adapt. This helps tremendously for DevOps, deployment security, managing things like white label licenses, and a host of other things.
Once you have it, it keeps you from writing terrible solutions to dance around having things like user account profiles. API keys if you need to offer them become easier and control of important assets are much less scary. Also you are ready to implement things like IAM management or whatever to keep track of deployment keys before you end up with a giant pile of security holes. JumpCloud offers a pretty turnkey IAM integration for AWS and others.
After that, getting paid. Figure out how to take money as fast as possible with the least friction. If you have auth and the ability to take money easy, pivots come a lot easier too. Since you have proper auth, things like subscription management becomes an easy reality without leaning on 3rd party vendors. Though just using stripe for that can be good enough, still you'll need to tie it to accounts. Especially if it's enterprise.
Something I've done recently that is now a part of my "get started fast" kit is automated DNS and TLS (via letsencrypt) with kubernetes. Might not be for everyone, but now that I'm on the other side, I'm not going back. I can tie a feature branch deploy via helm chart to it's own DNS endpoint defined as the host in the config, protect the ingress via LDAP, and make sure QA has an endpoint to review that won't be interrupted until the ticket is closed. One command and it's deployed and secure. Also this enables devs to deploy their own workspaces for effortless experimentation without disrupting dev/staging/prod, which shouldn't be used as sandboxes for features or QA IMO.
* http://www.jumpcloud.com
* https://www.keycloak.org/
* https://github.com/kubernetes/charts/tree/master/stable/exte...
* https://github.com/kubernetes/charts/tree/master/stable/cert...
* https://github.com/kubernetes/charts/tree/master/incubator/k...

#Tl;dr; Build relationships first, then build a reputation for your expertise, then implement changes.
Just for context, I’ve been working as a professional software developer for 22 years, but I let my career and knowledge stagnate until 2007 and became an “expert beginner” (https://daedtech.com/how-developers-stop-learning-rise-of-th...). I relaunched my career 11 years ago this month. So, how I’ve approached “what to change”, changed over the years...
2007 - started working at a small company. I took the job because they were looking for high level junior developers and were transistioning from VB6 to C# and they had a C++/MFC framework. It was the perfect position for me. I was really good at both their old technology and I was just getting into C#.
I didn’t try to change anything. I took the job to get some real world modern development experience and soaked everything in.
2011 - that company went out of business but by then, I knew C#, I could talk the talk about modern software engineering practices but I still needed more experience. I got a job at a Fortune 10 (at the time) company and learned how modern large software teams and organizations worked and was there to learn, not to change things. I took what I learned and leveraged it and my by then 20 years of on paper experience to get a job where they wanted someone to make significant changes to a slow moving dysfunctional software development department....
Again: My goal wasn’t to make changes, it was to keep my head down, not ruffle feathers and learn.
2014 - With both my manager’s and his manager’s blessing, I along with the other developers they hired, went in and started trying to make changes in the CI/CD process, getting rid of some bespoke custom libraries that could be implemented better using popular Nuget packages, and changing the testing process like bulls in china shop completely disregarding the feelings of the old guard. Eventually the old guard won, pushing both managers out and leaving the new hires without any cover.
Lessons learned: Build relationships first, respect the past decisions that got the company to where it is, and remember one of the “Laws of Power”, “Law 45: Preach the Need for Change But Never Reform Too Much at Once”. Try to win people over based on building relationships.
2016 - I started working at a new company with the official title of “Team Lead” where I was brought in to modernize the development department. I learned my lesson, first I built relationships, I respected the work the team did, engendered respect, and earned the loyalty of the team. Even though I had role power, I realized that wasn’t going to be effective without the relationship power.
I implemented version control, a real CI/CD process, automated testing, documentation standards, fought to reduce needless meetings and fought for the “40 hour work week”.
2017: I got another job at a small company as “just” a senior developer and an equal on paper. I quickly started building relationships and proving my expertise. I have far more influence to make changes based solely on doing that than I have ever had before.
Automation is always my hobby horse. First I implemented a sane CI/CD process and configuration management.
The next thing I’ve worked on is getting rid of single points of failure in both systems and people - I’m encouraging cross trainings.

1. Every now and then we run into Paywall. Give everyone employee debit card so that they can buy stuff which helps their productivity.
2. CI using Drone.io
3. Add trello
4. Everyone gets their own AWS account. It makes it trivial for them to experiment with new ideas from their home or at office without begging anyone for credentials.
You start by empowering your employees.
Now, we consult startups which work differently so you might not have capacity to make these changes.

Do you have a list of companies you consult for by any chance?

haha. seriously?

My company is currently using drone. The lack of first class scheduled builds is a real buzzkill. Jenkins or similar feels like a much better solution atm still (you can still push for containerizing jobs either way)

Jenkins's main problem for me will always be the lack of focus on storing pipelines/jobs as source code. Jenkinsfiles are horrible both to read and write.

I'm new to devops and thought it was crazy that Jenkins only recently implemented codified jobs (jenkinsfiles) and they truly are horrible to write.
Does anyone have any suggestions to resources or alternatives to jenkinsfiles?

I go from git to SVN. It's just easier for me to work with and once the team gets used to it, it's a win-win.

SVN is really heavyweight for branches and tags. It used to take like a minute to branch with SVN but when we swapped to git it took like less than a blink.
Also —rebase is way better than merge. I haven’t had to merge git for over 6 months but with SVN I was doing it twice daily, at least.

If you use a repository URL rather than a local filename / dirname in svn copy, it's a purely remote copy and is instantaneous:
$ svn copy file:///var/svn/repos/test/dir1 \ file:///var/svn/repos/test/dir1_jira_1886 -m "For bugfix to SERV-1886"
http://svnbook.red-bean.com/en/1.7/svn.branchmerge.using.htm...
https://svnvsgit.com/

Most of our team just used Tortoise SVN and the right click -> branch explorer integration. We definitely were not pros at source control.

Ah, I see! Tortoise SVN is great for the scenario where business users can learn and use revision control, too, but I guess once you're doing branching using Tortoise SVN, you're in a weird territory where you're pro, but not to the extent you're ready to use the command line...

We used to have a large (>20GB) svn repository, I never noticed tags (which was part of the build process) taking any time, certainly sub-second.
However the branching process in svn is a right pain, if you work in branches. Depends on what your code is if you need the overhead and risk of branches I guess.

That's because svn merge is much closer to what a git rebase is than what a git merge is.

So as soon as you get a new team, you make them stop using the thing they are comfortable with, so you can use the tool of your choice.
Man, that's such a dick move.

Reply on news.ycombinator.com