This is the most comprehensive and high quality writing I've seen that includes almost all engineering processes from interviewing to communication. Would love seeing other such engineering handbooks you've seen.
Man there are some real doozies in this repo's issues.
- an extensive month long discussion that leaks implementation details of a private repo and ultimately leads to adding 1 readme comment that merely _suggests_ something https://github.com/artsy/README/issues/459
- adding politically motivated language and starting a policy to open issues in dependencies that do not conform. Look at the time and energy putting into changing master -> main and white/blacklist -> allow/deny. Also https://github.com/artsy/README/issues/427
Somewhat unsure of what you're implying by the tone, but reading through the issues linked above and these seem like... um, good things? I know I'd certainly value working at a company that debates things through RFCs, supports hackathons, and puts real effort into updating every repo to eliminate racist historical baggage from git branch names.
Joey who opened https://github.com/artsy/README/issues/427 is one of the best 10x engineers I’ve ever had the privilege to work with. If it’s important to him to rename all branches from “master” to “joey” I’d add my plus 1.
> an extensive month long discussion that leaks implementation details of a private repo and ultimately leads to adding 1 readme comment that merely _suggests_ something https://github.com/artsy/README/issues/459
What implementation details? Most of the stuff linked in there seems to be in public repos that have interfaces to this private repo, so I can't see that the discussion itself is leaking more implementation details than reading the code in the public repos that interacts with the private repo.
Secondly, the conversation in there is long, but hardly unusually so. At most each comment apart from the initial one took up ~10 minutes of time for each of the authors. Are we at the point where 8 well-formatted comments on a GitHub issue are going to make us go "ooh, long discussion, must be something wrong with it"? I would rather have long, well-formatted comments than "lol ok" style garbage.
Finally, I wish more people would conclude a month-long discussion with a simple action rather than carrying out an unnecessary and complicated one because "Well, something has to be done, and it has to be large because we have discussed a lot". This can be counterproductive with dealing with complex libraries that you don't understand yet.
> adding politically motivated language and starting a policy to open issues in dependencies that do not conform. Look at the time and energy putting into changing master -> main and white/blacklist -> allow/deny. Also https://github.com/artsy/README/issues/427
I would prefer to stop talking about this stuff, but it's hard when I often see lazy drive-by denouncements like "Politically motivated" in comments near the top.
Language seems to be important to the people working on the project. It would probably not be the first thing I pick up, but I don't understand why it's considered a "doozy". Good documentation does think about the people using it as well as clarity; and "denylist" is more informational than "blacklist" in addition to being more sensitive. Real language idioms change just like programming language idioms, and railing against them is about as useful as claiming you hate Python 3 because they took out the print statement.
> Are we at the point where 8 well-formatted comments on a GitHub issue are going to make us go "ooh, long discussion, must be something wrong with it"?
Yeah, how about replacing it with 2/3 10 people meetings across 3 weeks lasting 60 minutes each?
You get 1800 minutes of work lost versus only 100 of yours and you also have the advantage of losing all of the information/context if the meeting contents aren't reported and documented.
Oh man I wish I could get my (non-tech) org to do this. Instead we’ve got a twisted hellscape of docx and pptx inside MS Teams and 3 other enterprise storage apps. If anything is documented at all, that is.
Just kidding. Yea, unfortunately I think a lot of people are suffering in the age of overtooling. Need a notes app, department X is using OneNote except for Mike, who is using Notely. Department Y uses obscure Markdown notes app with great PKM linkage, but no one outside of their group understands it (tbh, neither do they)...
Notes are just the example that I landed on. I'm sure the bigger tech companies have experienced this for awhile, but it slowly disseminates to other industries as well.
Maybe I'm just using HN as therapy, but things seem to have gotten over-complicated and under-defined. A seemingly endless churn of new tools.
Trying to work with my team (management team) on standardizing SharePoint setup, file structures, notes, etc. but it is really hard to get everyone on the same page.
It's nice to see such a nice functional/detailed design around an organizational tool.
A friend and I applied to YC in sept 2021 seeking funding to build tooling in this space. Lots of tools exist to help generate content. Lots of tools exist to help search some or all of it. No one is really building anything to enrich and expose the data with on ramps for folks. I don't know that our idea is/was any better but I feel the pain and I know lots of others do as well.
As for this Artsy stuff... their give-a-damn is through the roof. A+
Unfortunately I think the solution is very much the users and content, not the tools. What I mean by that is you need to have documentation on processes and workflow. That needs to be drilled into peoples heads and routinely audited.
As empowering as software is it really can allow for chaos when it comes to knowledge base. I don’t think there’s going to be any amount of integration with any one tooling that would make a solution click with all users. It always comes back to who the individuals are and how they perceive productivity.
They may be right as an individual. Tool X may be way better for them. A lot of us are working on teams though and with that we have to learn to adapt to what works for the team.
Back when I worked in a software company, everything had to be in a single database. Top down control by a CEO with an engineering bent seems to be the only way the chaos gets tamed.
Unfortunately my company is relatively diverse and we have different departments that do vastly different things. I would settle for an unambiguous narrative from our director though, who manages all the silos in out department.
I think that’s what me and my team of managers are on to (hopefully)
Artsy is open source by default so there are a fair amount of interesting repos and projects, including our website and mobile apps (react and react native).
I am biased of course but I think the engineering culture at Artsy is pretty unique and special.
we have this repo and others open source, bit of course these are used by us internally too. that means that we need to link to private stuff, but we want to keep all the links where they naturally would be. so that means that sometimes, non-artsy people just can't access these. and that's ok.
tl;dr The README became possible because Artsy is open-source by default, and someone just decided one day to create a repo and some content, and didn't need permission to do so. It's also the repo that most new hires read before they even apply to the job, and they don't need permission to make changes either. GitHub workflow is how everything gets done.
Does one of these documents (or any other source, not necessarily from Artsy) explain this concept of "open-source by default" and permissionlessness in and of itself?
I know the book "Turn the Ship Around" which talks of the difference between a culture of asking permission versus announcing intentions etc. Is it sort of like that?
We failed early. Had a wonderful demo day. Tons of sign ups. It started getting a bit long. Someone decided to shorten each session (max 2 minutes) and choose which ones were worth demoing. So you basically asked for permission to demo. Sign ups stopped. Nobody wanted to demo anymore. Demo day died and took a year to restart properly.
In general, establish “how”. Everything is in writing and GitHub workflow. When someone says “can I?” the answer is “why are you asking and haven’t done it (submit PR) yet”? This moves permission to a public discussion.
Think in terms of must have, should have, nice to have, not allow/disallow.
Managers already have the power to veto, so they don’t need to approve, allow or disallow. Managers need to say that to everyone all the time - “you have an idea, why haven’t you done it yet?”.
Everyone needs to do things very visibly and over communicate to enable gentle redirects and avoiding getting to veto.
Losing control is hard. Communications team wanted to review and control the engineering blog. I said hard no multiple times with every new comms leader. Asked them to comment on PRs.
Don’t fix problems that don’t exist. If someone wants a knob that looks like permission, ask them what problem they are trying to solve.
That sounds pretty similar to another place I worked that I have very mixed feelings about. There are a lot of paradoxes that need to be resolved there that weren't quite worked out.
For example: While an IC could technically just start doing something that he felt should just get done even if no manager had assigned him that task, it would have taken time away from tasks managers had in fact assigned. Now, while managers weren't allowed to reprimand that IC for doing unassigned tasks on their own initiative, they could reprimand him for not making enough progress on the assigned tasks. Some managers would do this systematically: Like if some work done by one of their underlings popped up somewhere that seemed to have taken a lot of time, they check extra hard (and push extra hard) on whether that individual is also making enough progress on assigned tasks. So, the individual is facing a choice of: Either I don't do any tasks from my own initiative and work normal hours, or I show a lot of initiative and work crazy hours. And people were working "all-in" contracts where they couldn't claim overtime pay.
Prima facie, it's still nice for people who are young and eager to prove themselves by working crazy hours. But the effect isn't what you'd think, namely that they'd get stellar careers out of it. Rather, it made managers less accountable when doing things like incurring technical debt and let them "off the hook" with regard to getting work done that's necessary to do but also a thankless task where the relationship to business objectives is not so visible. For example: automated testing, tooling, code quality, and so forth.
Managers always pushed extra-hard on super-tight project scopes and timelines, incurring technical debt and leaving it to individual developer initiative to pay back the debt. For example, towards the end of a project an IC might say to a manager "Okay, the functionality is there. Now let me just spend another week here to write some unit tests." The manager might say: "Sorry, no can do, I have another important project I need you to do and get started with right way."
We basically had one IC who worked himself silly keeping the test suite in good shape, writing unit tests for everybody else who hadn't written any. He was doing incredibly important work. But all the people around him got much better careers out of just doing highly-visible high-impact work that important managers needed to get done. When that IC, predictably left, unit tests were simply no longer maintained.
It's like when Bill Gates comes into a 3rd world country and just starts running healthcare out of his own pocket, and the government of that country is like: Thanks man. Now we (the "legitimate" rulers) no longer have to take care of this stuff, and are free to send even more of that tax money off to our swiss bank accounts.
There is also a paradox around "working in the open" and "overcommunicating" while being receptive to "gentle redirects", namely: What you actually want from bottom-up-ness and from empowering individuals is a pool of many people thinking independently and bringing their individual creativities to the task. But what you actually end up with is installing "group think" in every individual's mind. Because an IC who works openly in a way that goes against the grain of what managers want will just start hearing a lot of noes, sometimes soft-noes ("redirects"), sometimes hard noes ("vetoes"), and whenever that happens it works against that person's career. So the IC starts to internalize their managers' (or the whole group's) thinking, and starts to only do things that line up with that groupthink. -- See the book "Disciplined Minds" for a deeper explanation of how that comes about.
In one cycle, I even got performance feedback as part of the yearly performance evaluation which was saying "Unfortunately, we can't give you a raise this cycle. With regard to your stated career objective of stepping up from IC to manager we need to unfortunately tell you that this will not be happening this cycle. Here are some of the reasons: ..." And then the stated reasons are basically opinions that I have voiced that go against groupthink. Like if I spent a lot of time writing unit tests while everyone else thinks unit tests are a waste of time, it might say "You need to learn to be more pragmatic and waste less time on unit tests." I can't tell you how mad this made me. You can't, on one hand, preach this openness rhetoric and encourage people to always voice their opinions, and then use their opinions against them and punish them for "thoughtcrime".
Game-theoretically, the the strategy of playing as a "political animal" dominates the strategy openness. So it creates better outcomes for you, regardless of whether others are also playing as political animals or are being open.
So, personally, I really felt I got suckered into playing the "openness" game, making myself vulnerable, while the people in the informal/actual power structure just exploited my vulnerability to cement their own power and impose their will on everyone. It's not an experience I care to repeat, and I won't make that mistake again.
I am sorry you had this experience. No approach, closed or open, will ever substitute better leaders that aren’t taking advantage of you. Your experience is likely and sadly very common.
I was working at Artsy while the OP was CTO (:wave:) and tried to help out a bunch on fostering a good attitude towards OSS - there's quite a few notes in both artsy/README and the blog
How does this work? Do you just read it on github? Or you suppose to make copy of it on your computer. Looks like these are just linked md files. Is it similar to wiki? I'm confused.
Yep, it's just a repo of inter-linked markdown docs which you can view or edit on GitHub (or clone if you want to do some more involved editing.) You can definitely think of it as a wiki though as all engineers in the company would have write access.
I guess I'm in the minority here as a SWE but I find all this ongoing documentation about engineering expectations, culture, processes, etc. exhausting. I would not be excited to be onboarded somewhere that spends so much time and energy thinking and talking about a _proposal_ to document best practices and industry standards.
Perhaps I'm missing context but it all sounds so vague and low-impact that I just can't imagine spending so much time and energy engaging in these thought experiments on documentation improvements.
I understand the repo is for developer documentation but it took a long time of poking around to figure out what the product even was. Eventually I stumbled upon this blog post which seemed to anticipate my confusion and flat-out said: "For those unfamiliar, Artsy is a fine art marketplace." All the meta analysis is striking me as very distracted. Maybe its just the nature of the content but it seems like an inordinate amount of engineering resources are spent on process management, planning, and iterating on documentation thereof.
Reading this brings back some bad memories from working at a place that had something similar going, trying to be very open/transparent and deliberate about culture and processes. That culture and processes that existed on paper was about bottom-up power structures and so forth.
From that context, I can understand how people become very motivated to engage with these kinds of documents and have these kinds of discussions. It feels very empowering when suddenly you get to be a part of these conversations that are normally only had a few pay grades above yours. It's also a welcome change of scenery from the daily drudgery of a software engineering IC who lives breathes and works code, and nothing but code.
The problem, at the place where I worked, was that all of this amounted to nothing more than an "opium for the masses", and the informal/true power structures that lay behind all the decisions that actually mattered was very different from what existed "on paper".
So, all of this pretense of bottom-up-ness provides a motivation boost for new employees for maybe a year or two. But you can't hide the truth for longer than that. Afterwards, if you were naive enough to fall for it, you feel you've been manipulated and abused, and that's not a nice feeling. Also, the whole thing can take on a cult-like dynamic.
Artsy never had a large engineering team, and yet, it was deeply respected. (Maybe still is, I've not been an IC for a while.)
For me personally, the engineering team's reputation was a major draw for me to work there. And while I managed engineers at Artsy, I could see how much it helped immensely with recruiting.
And it's not just talk, we published many of our apps and libraries. Some of these, like Ezel and Fresnel, have been pretty influential. Many Artsy engineers also developed projects on the side, which were piloted in production within the company, like Danger/Peril.
No environment works for everyone, so if it sounds exhausting, maybe you wouldn't be into it. But for me, I found it nourishing, challenging, and productive.
Also adding two other good ones: Sourcegraph - https://handbook.sourcegraph.com/ & Gitlab - https://about.gitlab.com/handbook/#engineering