Kate Heddleston is freaking awesome, if you don't know. Her talk at Pycon 2015 about diversity in engineering environments is fantastic. Well explained in language free of activist rhetoric -- it was a pragmatic and thoughtful speech. Her blog expands on much of what she covers and should be read.
On the topic of on-boarding -- super important to get right! The idea of making your people the best they can be is lost, I think, on our generation. My grandfather-in-law was a mechanical engineer at Chrysler back in the day when they had a special school they ran to train their new recruits. When he started he had no idea of how cars worked but they picked him up from school and gave him the training he needed to become an important figure in their company.
Focusing on hiring the best because hiring someone mediocre will damage your business is negative thinking that can kill your on-boarding, and thus your culture and business. I've worked at places with terrible on-boarding and it was a fight just to get some direction and support for your work. Getting the attention of management was something you wanted to avoid which led to people becoming complacent about their work and its quality.
Great article. On-boarding is important to get right.
Regarding the negative thinking, this is a really important point. Consider these two alternative attitudes when on-boarding a new employee:
1. Let's evaluate to see whether the new developer is good enough, so we can fire fast if our expectations are not met.
2. Let's figure out how to help this developer achieve his/her maximum potential for adding value to the organization. If for some reason the developer is unwilling or unable to develop to a level that makes a positive contribution, then we consider separating.
I find the second approach much healthier for the employee and the organization.
It's not that the idea of making your people the best they can be is lost. It's that our industry has accept job-hopping as normal, with the side-effect of limiting how much training a company is willing to invest in someone who stands a good chance of being gone in three years.
The notion has less been lost and more been re-evaluated in a new context.
Bloomberg does this for its software engineers. I know a few of their software developers (one was EE, one ME) who were both very sharp guys that they trained while paying them for six months while they sat in classes (at Bloomberg from a current Software Engineer) to develop for the Bloomberg terminal. Great way to introduce new talent to the company while also training them for the role.
The point you make about hiring ordinary people is an important one. The timeless, old essay "Why I Never Hire Brilliant Men"[1] makes a lot of great arguments to this end.
The meat of the essay comes down to this quote:
Business and life are built upon successful mediocrity; and victory comes to companies, not through the employment of brilliant men, but through knowing how to get the most out of ordinary folks.
Your grandfather-in-law is the perfect example of something I wish we'd see more of today.
Kate's talk at PyCon Sweden was one of my favorites. It's called "The Ethics of Being a Programmer." Here's the video for anyone interested in watching:
Onboarding is a people/process/docs/technology problem. To the limited extent that it is a technology problem, you really can't go wrong with a) treating it like it is an actual shipping product of the company (implying a minimum standard of care like e.g. a repository, documentation about it, and a dedicated place to put issues) and b) actively maintaining something with the goal of getting someone up-and-running quickly.
None of my projects are at the point where you can just "vagrant up and go", but the next-best thing has been READMEs in the relevant repositories with exact lists of "Type this, type this, type this, type this. You now have a fully-working system running on localhost and you should be able to type this to get a full green test suite. If you can type this and it does not come out green, fixing that is more important than anything Patrick is doing right now."
Here's, for example, what we have for getting someone up and running on Appointment Reminder (in preparation for me soon no longer being the engineer who keeps all of that system in my head): https://gist.github.com/patio11/a0b1063c5d33b5748da6 Feel free to steal ideas in terms of level of detail or useful things to include. (A lot of the magic is in the rake commands like "setup_site", which take care of "All that crufty configuration stuff which you would otherwise need a senior engineer to do for you prior to actually seeing the page render correctly on localhost:3000.")
Quick hack which helped us on making sure this guide was actually accurate: we had two engineers coming into the project at the same time. I wrote down everything I thought they needed to know. Engineer #1 implemented to the document I had written, filled in the blank spots where he needed to ask questions, and then we committed the readme. Engineer #2 then had to do it off the readme without asking me any questions. Given that he was actually able to do this, we have high confidence that there is not at the moment anything rattling around in my head which is absolutely required to get up-and-running and documented nowhere else.
That's a great example of practical documentation. I just want to add that for a fair amount of developers they are not going to be successful unless they get an hour+ meeting a couple times a week for the first month for questions and a general birdseye tour of the architecture.
Things like "I know most people do this, but we are expecting to swap this feature out in two months so that's why it's put together like that so just roll with it and spend a few extra minutes manually testing before you ship it." or "Employee X is in the middle of refactoring all of this but is putting out a fire for the next couple weeks. If you need to do something here get in touch with him and what you want to do and he'll either walk you through it or apply the fix himself".
Unfortunately the personality type of a 10x developer is often not going to be like your 1-2x developer. Pointing them to some documentation and walking away often will lead to an unsuccessful onboarding. This may be preferable if you are actively testing out the new hire and really want fully independent developers, but if you are not knee deep in talent some verbal onboarding can work wonders.
Thanks a ton for this. I've been recently looking for examples to follow as no readme or style is perfect but this is a worthy goal for any software project to me, be it internal or external, closed or open source.
I think the key to make it successful is to have the feedback of someone actually working through it, finding the pitfalls or shortcomings, and correcting as they go. I know I tend to "just figure it" out but I've been in plenty of places with little to absolutely no documentation. It behooves me that if someone did take the time to document something, I should honestly take the time to "pay it forward" by keeping it current as I work through it. It's also far too easy to let this learned skill stagnate when you aren't required to document anything so absolutely no one does it.
That quick hack is exactly the approach we've taken with new technical hires this summer. We are a "vagrant up and go" shop, but there are a bunch of steps between handing someone a laptop and running your app in vagrant. We took the time to document the process and used it in onboarding. We made it explicitly clear that if you notice issues, please fix them, which has the intended side effect of familiarizing the new hire with our development practices (pull requests, reviews, etc).
This sounds like a great approach; however, what is precluding you from making this into a script ? Maybe with a first step of "fill values in this properties file" for passwords etc ?
I worked for one company for a month. From the get go they had 100+ staff but no onboarding. Nobody knew how to set up the development environment or even get the application working on the company laptop. Nobody could show me how to VPN to client sites or show me how the software worked. I was meant to support it...
I was in my manager's office every day letting her know hey I really need assistance here, nobody seems to have time, nothing is working, I'm not learning anything and this needs to improve.
She'd tell staff to assist and they just wouldn't. And rinse wash repeat the next day.
A month in we are in a meeting and some difficult software issue comes up and it's assigned to me to fix. I mention that I don't have it running, don't know how to use it, have no method of finding who the customer contacts are to call them and will sound stupid not understanding anything, but also haven't been shown how to connect in. That I'm happy to shadow someone else and learn it.
It felt shameful but I knew it was the right thing, I had a year of extensive help desk experience under my belt including programming and other development, bug fixing, accounting, you name it, I was even team lead. I was used to dealing with multi million dollar clients and had no qualms about doing so... but this place was dysfunctional.
Anyway the boss stared me in the face in the meeting and called me a liar, to shut up and get to work. I was stunned. I repeated myself and she turned to my coworkers who claimed they had "showed me everything". I hadn't spent more than 5 minutes with them in the entire month and had been in her office every day. She told me to start pulling my weight and stop lying.
I walked very calmly to the office printed out a resignation and left my keys and walked out the door. I didn't get paid (a funny side effect of walking out of a job) and the move left me penniless and ALMOST homeless.
Luckily I got a job just in the nick of time shortly after, at twice the pay, and being treated like a human being. I removed that place off my resume and rarely discuss it because it's so humiliating.
I still remember the recruiter calling me screaming how unprofessional I was - he only cared about his lost bonus. I explained I was extremely professional but that after being humiliated and called a liar in a meeting and having none of the promised training, or anything remotely capable of making me a functional employee, there was no recovery.
I too had a similar experience. Senior dev at our open office rushed to my desk after I asked him to clarify about some email instructions he sent me. Told me to read the instructions out loud in front of the entire company. I laughed it off but he was really persistent. Just disconnected my laptop, and told him he can explain to the CEO why there's no longer a frontend department (I was lead frontend, and I got friends hired who I run a sideproject with, so we all just up and left, but we've been planning to for some time. This was the final straw.)
I'm in the midst of being onboarded at a very large healthcare organization. In addition to the complex SOA infrastructure, we deal with a multitude of databases, accessible through many different methods, from a number of vendors. There's a ton to take in—not to mention the business complexity inherent to the organization as a whole.
Heddleston's point about having less-senior people do the mentoring is especially apt. While I've received support from everyone in the team, the most helpful person has actually been an intern with only a few years of programming experience under his belt. While I have over a decade more general programming experience than he has, he knows a lot more about the specific domain, and has been an excellent teacher. I feel that this arrangement has been beneficial for both of us—as I've gained domain knowledge, he's gained confidence and depth in his own knowledge.
I think that a big part of this is not setting expectations too high—no matter how senior the new employee is. While I have a fair amount of experience, the expectation in my new position—both from me and from the team—is that it will take me a while to get up to speed,(especially given the complexity inherent to the role), even though I'm not coming in as a junior dev. Therefore, I don't feel the need to pretend that I'm an expert in something that I'm not, and there's no ego hit when I'm being mentored by someone who is technically my junior.
In my city, it seems like most everyone is looking for senior devs—to the point that they leave positions unfilled for months rather than hiring someone they don't consider senior enough. This is madness, and damaging to the industry as a whole. We need to focus more on efficiently developing talent, and Heddleston seems to have some great ideas for doing so.
I think outside of the day-to-day (you need to know Python, here's how to get Vagrant running, this is how you submit a code review) there can also be a gap in cultural onboarding. For example, someone moving from a large tech company to a startup has certain norms and expectations that they may slowly re-evaluate (if they actually do) over a number of weeks or months, potentially harming the product and even their own career -- for example, "that's not in my job description" doesn't fly at a startup but can be a protective reflex at a large company. (One may argue someone with this attitude may not be hired at a startup in the first place, but sometimes the attitudes and expectations aren't so upfront and clear-cut, and are hard to test for at interview!)
Would love to find some examples of great cultural onboarding where it's not just the "what" of the work that a new hire learns, but also the why and how, to avoid implicit assumptions and biases from day one...
I ran twitter's new engineer training for a long time, and much of this rings pretty true to me. I would only add 3 things:
-1 the skill of teaching is approximately orthogonal to domain knowledge, and the difference between a decent and very good teacher is huge, both in terms of student-reported happiness and in terms of retention of the material covered.
-2 history with the company tends to be very valuable, in that new hires are often curious about _why_ the company decided to build system X as it was. My goal was that teachers should be able to answer most such questions accurately, and truthfully say that they didn't know in the other cases. I found (anecdotally, because this data is hard to capture) that the student-reported quality of a class was generally proportional to the maximum length of question/answer/followup q/answer/... chains.
-3 the onboarding process is an extremely powerful propaganda platform. During twitter's long transition from ruby to scala, (before I ran it) there were a series of presentations that were forward looking to the point of inaccuracy: they described as existing in the present that which we hoped would one day exist. This confused a bunch of new engineers when the rainbow unicorn scala world promised them did not materialize. On the positive side, many of them were then motivated to help build a scala world.
Does anyone actually work as a QA for documentation? I've been in many projects where "just read the docs" or "go read this doc", and... nearly always it's out of date, or missing key information (like who wrote it, who to contact for access to systems in the document, etc) or so scantily written as to be useless.
Saying "I wrote docs" but having them be abysmal seems to be the norm. People now accept that having unit tests for code is a thing (not always done, but at least a thing) - is there an equivalent for documentation?
I'm surprised literate programming[0] never really caught on.
Rather than have separate documentation, the paradigm is completely different. Source code generation is interspersed with the abstract flow of thoughts that one usually has while developing.
This style of coding seems to be natural to me, as many algorithms are a set of discrete steps in an abstract sense. Implementing concrete steps and then describing their abstract counterparts seems sort of backwards to me.
great point about onboarding providing a high ROI, it's something I haven't thought enough about. this is a particularly useful part: "The best person to help someone set up their development environment is the last person who joined, regardless of seniority."
An inability to bring on new talent, junior or otherwise, is a symptom of lacking essential documentation. If I can't come into your office and have a copy of your software running or successfully compiling on my machine in less than an hour, something is very wrong with your documentation, tooling, or (lack of) build process.
"Here's Jim. He's our Widgitsoft guy. He's the only one who works on Widgitsoft. The system is entirely undocumented because Jim knows everything. Yeah, development has been slower than expected lately. Yeah, it would be nice if we could bring on a contractor when necessary, but getting to that point would be a lot of work, and we'll always have Jim."
If I can't come into your office and have a copy of your software running or successfully compiling on my machine in less than an hour, something is very wrong with your documentation, tooling, or (lack of) build process.
So that's why your first project here is going to be writing up some stuff so that it's easier to bring future people on board!
Also there has to be very clear guidelines - Use the wikki to set up. if you get stuck ask us, but anything you ask needs to make it back in the wikki.
I have never seen a wikki stay 100% in sync with the real world. But make people edit the wikki as part of using it, and things change.
This is timely, as I’ve just gone through the worst onboarding I've ever experienced. It took two very long days to install an OS on a machine and get it to boot (I had to assembly my computer and then use the corporate installer, which failed multiple times with errors like “an unknown error occurred”). It then took me about a week to run the local project’s “hello world” (I was initially pointed to documentation that had been deprecated for months, and then when I found the right documentation it was incomplete and out of date). The actual process to get there was hilariously baroque; for example (if my email records are correct and I didn’t get duplicate emails from the system), I must have clicked through 18 EULAs to get a subset of the permissions I need. I promise, that’s worse than it sounds since the form to do so took more time to click through than you can imagine. It was a month before I could effectively do any work at all.
I originally thought that I was just unlucky, but when I asked around I found that I had an above average experience, at least among people near me who started recently. Unlike many other folks, I was actually able to get a username/alias, a computer, and an office. I don’t know what folks without a username do since they can’t even start clicking through the necessary EULAs to get permissions to do stuff, let alone do any actual work.
I’m not sure how it is in other parts of the company, but if you imagine that it’s similar and do some back of the envelope math on how many people get onboarded and how much losing a month (or more) of time costs, it comes out to N million dollars for a non-trivial N. And that’s just the direct cost of the really trivial stuff. It’s hard to calculate the cost of the higher level stuff that’s mentioned in the article, but I suspect that’s even more expensive.
Standout quote: "People think that confidence follows skills, but it’s usually the other way around where skills follow confidence." This is a fact that really needs to be more widely acknowledged. (It also casts the microagressions that have the effect of chipping away at the confidence of women and minorities in a rather uncomfortable light.)
I've been learning to interviewing potential hires. One of the questions I ask is, "Do you have any questions for us?" The questions can tell a lot about the prospective hire.
Turn this around: "What is your onboarding process?" is a great question from prospective hires.
This past year, having taken a number of short-term contracts at small teams, I've learned the hard way how to survive getting thrown into the deep end. You have to get really aggressive about communication, especially on a remote team. A lot of expectations can get lost. It's possible to survive and thrive without a good on-boarding process, but you have to step up and assume that responsibility yourself.
This isn't everyone's thing, and often feels like straying into rude, invasive behavior -- and from the startup's perspective, you lose a lot of great people too -- so asking this question will give the prospective hire an idea of whether they are getting set up for failure. Even an honest answer from the potential employer, "We don't have one, we are very busy and everything is really chaotic here" will tell you a lot about expectations (for both parties) within the first couple weeks of starting work.
And obviously, if the potential employer gives some BS in lieu of a straight answer, why waste time joining?
I think lack of onboarding is probably one of the biggest problems with open source projects as well. You can't expect to get new contributors, if you have no documentation on how to setup a development environment, which tools you use and how the project is structured.
The form of the interview was a bit weird: All the questions seemed to be entirely predetermined, with no follow-up questions and no opportunity for the answers to guide the direction of the interview. But on the other hand they were open-ended enough that it was more like a talk where the interview questions were hardly needed – essentially:
So I heard you like x.
How did you get started with x?
Tell us a few things about x.
In addition to those things, could you tell us something more about x?
Is there anything else you want to say about x?
I really enjoyed this video as I am currently looking for programmers and coders. I am leaning towards female engineers as I am a proponent of diversity and that I want to produce gender neutral software for my market. My goal is to hire the "right" people who can objectively work together while also producing software that takes multiple points of view into its development.
I don't agree with all the advice, but I do think it's a good message. My favorite part is actually on pre-onboarding: "If everyone has to come in and manually set up everything, what you have is this super painful onboarding process that’s just going to bottleneck your company."
My Induction at my first job after being issued with my labcoat was an hours instruction on how to boot the PDP11/40 and I was told ah the company library has a book on FORTRAN go and learn it :-)
[+] [-] agentultra|10 years ago|reply
On the topic of on-boarding -- super important to get right! The idea of making your people the best they can be is lost, I think, on our generation. My grandfather-in-law was a mechanical engineer at Chrysler back in the day when they had a special school they ran to train their new recruits. When he started he had no idea of how cars worked but they picked him up from school and gave him the training he needed to become an important figure in their company.
Focusing on hiring the best because hiring someone mediocre will damage your business is negative thinking that can kill your on-boarding, and thus your culture and business. I've worked at places with terrible on-boarding and it was a fight just to get some direction and support for your work. Getting the attention of management was something you wanted to avoid which led to people becoming complacent about their work and its quality.
Great article. On-boarding is important to get right.
[+] [-] sjcrank|10 years ago|reply
1. Let's evaluate to see whether the new developer is good enough, so we can fire fast if our expectations are not met.
2. Let's figure out how to help this developer achieve his/her maximum potential for adding value to the organization. If for some reason the developer is unwilling or unable to develop to a level that makes a positive contribution, then we consider separating.
I find the second approach much healthier for the employee and the organization.
[+] [-] Kalium|10 years ago|reply
The notion has less been lost and more been re-evaluated in a new context.
[+] [-] littleweep|10 years ago|reply
[+] [-] mattyb|10 years ago|reply
https://www.youtube.com/watch?v=kNke_4WOWAU
https://speakerdeck.com/pycon2015/kate-heddleston-how-our-en...
[+] [-] svensken|10 years ago|reply
The meat of the essay comes down to this quote:
Business and life are built upon successful mediocrity; and victory comes to companies, not through the employment of brilliant men, but through knowing how to get the most out of ordinary folks.
Your grandfather-in-law is the perfect example of something I wish we'd see more of today.
1: https://en.m.wikisource.org/wiki/Why_I_Never_Hire_Brilliant_...
[+] [-] nicolewhite|10 years ago|reply
https://www.youtube.com/watch?v=DB7ei5W1eRQ
[+] [-] patio11|10 years ago|reply
None of my projects are at the point where you can just "vagrant up and go", but the next-best thing has been READMEs in the relevant repositories with exact lists of "Type this, type this, type this, type this. You now have a fully-working system running on localhost and you should be able to type this to get a full green test suite. If you can type this and it does not come out green, fixing that is more important than anything Patrick is doing right now."
Here's, for example, what we have for getting someone up and running on Appointment Reminder (in preparation for me soon no longer being the engineer who keeps all of that system in my head): https://gist.github.com/patio11/a0b1063c5d33b5748da6 Feel free to steal ideas in terms of level of detail or useful things to include. (A lot of the magic is in the rake commands like "setup_site", which take care of "All that crufty configuration stuff which you would otherwise need a senior engineer to do for you prior to actually seeing the page render correctly on localhost:3000.")
Quick hack which helped us on making sure this guide was actually accurate: we had two engineers coming into the project at the same time. I wrote down everything I thought they needed to know. Engineer #1 implemented to the document I had written, filled in the blank spots where he needed to ask questions, and then we committed the readme. Engineer #2 then had to do it off the readme without asking me any questions. Given that he was actually able to do this, we have high confidence that there is not at the moment anything rattling around in my head which is absolutely required to get up-and-running and documented nowhere else.
[+] [-] hiou|10 years ago|reply
Things like "I know most people do this, but we are expecting to swap this feature out in two months so that's why it's put together like that so just roll with it and spend a few extra minutes manually testing before you ship it." or "Employee X is in the middle of refactoring all of this but is putting out a fire for the next couple weeks. If you need to do something here get in touch with him and what you want to do and he'll either walk you through it or apply the fix himself".
Unfortunately the personality type of a 10x developer is often not going to be like your 1-2x developer. Pointing them to some documentation and walking away often will lead to an unsuccessful onboarding. This may be preferable if you are actively testing out the new hire and really want fully independent developers, but if you are not knee deep in talent some verbal onboarding can work wonders.
[+] [-] w0rd-driven|10 years ago|reply
I think the key to make it successful is to have the feedback of someone actually working through it, finding the pitfalls or shortcomings, and correcting as they go. I know I tend to "just figure it" out but I've been in plenty of places with little to absolutely no documentation. It behooves me that if someone did take the time to document something, I should honestly take the time to "pay it forward" by keeping it current as I work through it. It's also far too easy to let this learned skill stagnate when you aren't required to document anything so absolutely no one does it.
[+] [-] nemild|10 years ago|reply
http://githubengineering.com/scripts-to-rule-them-all/
[+] [-] stephendicato|10 years ago|reply
It worked extremely well!
[+] [-] okaram|10 years ago|reply
[+] [-] sqldba|10 years ago|reply
I worked for one company for a month. From the get go they had 100+ staff but no onboarding. Nobody knew how to set up the development environment or even get the application working on the company laptop. Nobody could show me how to VPN to client sites or show me how the software worked. I was meant to support it...
I was in my manager's office every day letting her know hey I really need assistance here, nobody seems to have time, nothing is working, I'm not learning anything and this needs to improve.
She'd tell staff to assist and they just wouldn't. And rinse wash repeat the next day.
A month in we are in a meeting and some difficult software issue comes up and it's assigned to me to fix. I mention that I don't have it running, don't know how to use it, have no method of finding who the customer contacts are to call them and will sound stupid not understanding anything, but also haven't been shown how to connect in. That I'm happy to shadow someone else and learn it.
It felt shameful but I knew it was the right thing, I had a year of extensive help desk experience under my belt including programming and other development, bug fixing, accounting, you name it, I was even team lead. I was used to dealing with multi million dollar clients and had no qualms about doing so... but this place was dysfunctional.
Anyway the boss stared me in the face in the meeting and called me a liar, to shut up and get to work. I was stunned. I repeated myself and she turned to my coworkers who claimed they had "showed me everything". I hadn't spent more than 5 minutes with them in the entire month and had been in her office every day. She told me to start pulling my weight and stop lying.
I walked very calmly to the office printed out a resignation and left my keys and walked out the door. I didn't get paid (a funny side effect of walking out of a job) and the move left me penniless and ALMOST homeless.
Luckily I got a job just in the nick of time shortly after, at twice the pay, and being treated like a human being. I removed that place off my resume and rarely discuss it because it's so humiliating.
I still remember the recruiter calling me screaming how unprofessional I was - he only cared about his lost bonus. I explained I was extremely professional but that after being humiliated and called a liar in a meeting and having none of the promised training, or anything remotely capable of making me a functional employee, there was no recovery.
Now I take onboarding very seriously.
[+] [-] EC1|10 years ago|reply
Felt amazing but I was also super broke.
[+] [-] afarrell|10 years ago|reply
Wait, you didn't get paid for the time you had been their? I'm pretty sure that is a violation of labor law, at least in any state in the US.
[+] [-] JabavuAdams|10 years ago|reply
What. The. Fuck. You are a less violent person than I am. Glad it worked out.
[+] [-] unknown|10 years ago|reply
[deleted]
[+] [-] organsnyder|10 years ago|reply
Heddleston's point about having less-senior people do the mentoring is especially apt. While I've received support from everyone in the team, the most helpful person has actually been an intern with only a few years of programming experience under his belt. While I have over a decade more general programming experience than he has, he knows a lot more about the specific domain, and has been an excellent teacher. I feel that this arrangement has been beneficial for both of us—as I've gained domain knowledge, he's gained confidence and depth in his own knowledge.
I think that a big part of this is not setting expectations too high—no matter how senior the new employee is. While I have a fair amount of experience, the expectation in my new position—both from me and from the team—is that it will take me a while to get up to speed,(especially given the complexity inherent to the role), even though I'm not coming in as a junior dev. Therefore, I don't feel the need to pretend that I'm an expert in something that I'm not, and there's no ego hit when I'm being mentored by someone who is technically my junior.
In my city, it seems like most everyone is looking for senior devs—to the point that they leave positions unfilled for months rather than hiring someone they don't consider senior enough. This is madness, and damaging to the industry as a whole. We need to focus more on efficiently developing talent, and Heddleston seems to have some great ideas for doing so.
[+] [-] jlees|10 years ago|reply
Would love to find some examples of great cultural onboarding where it's not just the "what" of the work that a new hire learns, but also the why and how, to avoid implicit assumptions and biases from day one...
[+] [-] mattknox|10 years ago|reply
[+] [-] mgkimsal|10 years ago|reply
Does anyone actually work as a QA for documentation? I've been in many projects where "just read the docs" or "go read this doc", and... nearly always it's out of date, or missing key information (like who wrote it, who to contact for access to systems in the document, etc) or so scantily written as to be useless.
Saying "I wrote docs" but having them be abysmal seems to be the norm. People now accept that having unit tests for code is a thing (not always done, but at least a thing) - is there an equivalent for documentation?
[+] [-] yarou|10 years ago|reply
Rather than have separate documentation, the paradigm is completely different. Source code generation is interspersed with the abstract flow of thoughts that one usually has while developing.
This style of coding seems to be natural to me, as many algorithms are a set of discrete steps in an abstract sense. Implementing concrete steps and then describing their abstract counterparts seems sort of backwards to me.
[0] https://en.wikipedia.org/wiki/Literate_programming
[+] [-] vehementi|10 years ago|reply
[+] [-] egusa|10 years ago|reply
[+] [-] debacle|10 years ago|reply
[+] [-] debacle|10 years ago|reply
"Here's Jim. He's our Widgitsoft guy. He's the only one who works on Widgitsoft. The system is entirely undocumented because Jim knows everything. Yeah, development has been slower than expected lately. Yeah, it would be nice if we could bring on a contractor when necessary, but getting to that point would be a lot of work, and we'll always have Jim."
[+] [-] bluedino|10 years ago|reply
So that's why your first project here is going to be writing up some stuff so that it's easier to bring future people on board!
[+] [-] brianwawok|10 years ago|reply
I have never seen a wikki stay 100% in sync with the real world. But make people edit the wikki as part of using it, and things change.
[+] [-] luu|10 years ago|reply
I originally thought that I was just unlucky, but when I asked around I found that I had an above average experience, at least among people near me who started recently. Unlike many other folks, I was actually able to get a username/alias, a computer, and an office. I don’t know what folks without a username do since they can’t even start clicking through the necessary EULAs to get permissions to do stuff, let alone do any actual work.
I’m not sure how it is in other parts of the company, but if you imagine that it’s similar and do some back of the envelope math on how many people get onboarded and how much losing a month (or more) of time costs, it comes out to N million dollars for a non-trivial N. And that’s just the direct cost of the really trivial stuff. It’s hard to calculate the cost of the higher level stuff that’s mentioned in the article, but I suspect that’s even more expensive.
[+] [-] walshemj|10 years ago|reply
[+] [-] breadbox|10 years ago|reply
[+] [-] hosh|10 years ago|reply
I've been learning to interviewing potential hires. One of the questions I ask is, "Do you have any questions for us?" The questions can tell a lot about the prospective hire.
Turn this around: "What is your onboarding process?" is a great question from prospective hires.
This past year, having taken a number of short-term contracts at small teams, I've learned the hard way how to survive getting thrown into the deep end. You have to get really aggressive about communication, especially on a remote team. A lot of expectations can get lost. It's possible to survive and thrive without a good on-boarding process, but you have to step up and assume that responsibility yourself.
This isn't everyone's thing, and often feels like straying into rude, invasive behavior -- and from the startup's perspective, you lose a lot of great people too -- so asking this question will give the prospective hire an idea of whether they are getting set up for failure. Even an honest answer from the potential employer, "We don't have one, we are very busy and everything is really chaotic here" will tell you a lot about expectations (for both parties) within the first couple weeks of starting work.
And obviously, if the potential employer gives some BS in lieu of a straight answer, why waste time joining?
[+] [-] DasIch|10 years ago|reply
[+] [-] cocoflunchy|10 years ago|reply
Kind of crazy...
[+] [-] scrabble|10 years ago|reply
[+] [-] ptx|10 years ago|reply
[+] [-] dhutchinson|10 years ago|reply
[+] [-] snlacks|10 years ago|reply
[+] [-] walshemj|10 years ago|reply
[+] [-] lutorm|10 years ago|reply
[+] [-] dllthomas|10 years ago|reply
[+] [-] jxm262|10 years ago|reply