20 ms·

Artsy Engineering Handbook

217 points by rnjailamba 4y ago

rnjailamba 4y ago
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. Also adding two other good ones: Sourcegraph - https://handbook.sourcegraph.com/ https://handbook.sourcegraph.com/ & Gitlab - https://about.gitlab.com/handbook/#engineering https://about.gitlab.com/handbook/#engineering
- chucksmash 4y ago
  It's an Employee Handbook, not an Engineering Handbook, but Valve's is very, very well produced[1]. [1] (PDF): https://cdn.akamai.steamstatic.com/apps/valve/Valve_NewEmployeeHandbook.pdf https://cdn.akamai.steamstatic.com/apps/valve/Valve_NewEmplo...
hhh 4y ago
I wouldn't have discovered the site if not for this handbook. Pretty cool way to find new art.
xwowsersx 4y ago
I really admire the organization and clarity of this documentation. I'm going to take a lot of inspiration from this. Good work.
maliker 4y ago
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.
- procarch2019 4y ago
  John? 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.
  - maliker 4y ago
    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.
    - procarch2019 4y ago
      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)
  - leetrout 4y ago
    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+
    - procarch2019 4y ago
      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.
maroonblazer 4y ago
I'd love to know the background of how something this comprehensive is created and maintained. Was this the work of one person? A team? Was it created in one go or did it start small and evolve? Very impressive!
- alexeldeib 4y ago
  Probably helps that the first suggestion is to PR the README :) More seriously, I agree. Reading this doc, the values, etc, make me want to work for this company I’d never heard of before.
- dblock 4y ago
  (I was CTO of Artsy then.) 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. More practically, check out https://github.com/artsy/meta/pull/1 https://github.com/artsy/meta/pull/1, which is one of the repos that merged into the handbook via https://github.com/artsy/README/pull/1 https://github.com/artsy/README/pull/1. Also note that Artsy was founded in 2010. This handbook in its current iteration is 7-8 years in, but its content goes back to ~2011 in some kind of evolution. You'll want to check out https://artsy.github.io/blog/archives/ https://artsy.github.io/blog/archives/ as well.
  - stakhanov 4y ago
    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?
    - orta 4y ago
      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 - (the making of artsy/README) https://artsy.github.io/blog/2018/08/21/OSS-by-Default-Docs/ https://artsy.github.io/blog/2018/08/21/OSS-by-Default-Docs/ - (OSSing our apps) https://artsy.github.io/blog/2019/04/29/how-did-artsy-become-oss-by-default/ https://artsy.github.io/blog/2019/04/29/how-did-artsy-become... - (OPs writeup on the philosophy) https://code.dblock.org/2015/02/09/becoming-open-source-by-default.html https://code.dblock.org/2015/02/09/becoming-open-source-by-d... - (the RFC process) https://artsy.github.io/blog/2019/04/11/on-an-rfcs-process/ https://artsy.github.io/blog/2019/04/11/on-an-rfcs-process/
TruthWillHurt 4y ago
Amazing how you keep updating it
stefap2 4y ago
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.
- orta 4y ago
  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.
brainbicycle 4y ago
:disclaimer I work at Artsy: cool to see this on the front page! If this interests you be sure to check out the artsy org on github: https://github.com/artsy https://github.com/artsy 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. The blog and podcast may also be of interest: https://artsy.github.io/open-source/ https://artsy.github.io/open-source/ https://podcasts.apple.com/us/podcast/artsy-engineering-radio/id1545870104 https://podcasts.apple.com/us/podcast/artsy-engineering-radi...
- deleted 4y ago
  [deleted]
- talhachy 4y ago
  Can you tell me if the product part is mistakenly locked or is there any way I could get access to the resource?: https://github.com/artsy/README#:~:text=in%20the%20Product,%F0%9F%94%91 https://github.com/artsy/README#:~:text=in%20the%20Product,%...
  - pvinis 4y ago
    links with the key emoji next to it are private. 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.
nonethewiser 4y ago
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.
- deleted 4y ago
  [deleted]
  - deleted 4y ago
    [deleted]
- stakhanov 4y ago
  I'm tentatively with you. 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.
poyes99680 4y ago
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 https://github.com/artsy/README/issues/459 - starting a 3 full-day hackathon every quarter. https://github.com/artsy/README/issues/441 https://github.com/artsy/README/issues/441 - 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 https://github.com/artsy/README/issues/427
- aba30 4y ago
  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.
  - tkiolp4 4y ago
    Hackathons are (if any) for people in their 20s with no family/kids. For me companies doing hackathons is a red flag.
    - statusgraph 4y ago
      Company hackathons are rarely 24hr affairs and more "don't do your normal work during working hours"
      - deleted 4y ago
        [deleted]
    - dblock 4y ago
      My daughter (second child) was born 4 days after I started at Artsy. Some of the best new ideas came from hackathons.
ArtWomb 4y ago
>>> NYC Mobile Forum ??? Like Brecht Forum? Is there a space to revive this weekly convening ;)

217 points by rnjailamba 4y ago

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. Also adding two other good ones: Sourcegraph - https://handbook.sourcegraph.com/ https://handbook.sourcegraph.com/ & Gitlab - https://about.gitlab.com/handbook/#engineering https://about.gitlab.com/handbook/#engineering

chucksmash 4y ago
It's an Employee Handbook, not an Engineering Handbook, but Valve's is very, very well produced[1]. [1] (PDF): https://cdn.akamai.steamstatic.com/apps/valve/Valve_NewEmployeeHandbook.pdf https://cdn.akamai.steamstatic.com/apps/valve/Valve_NewEmplo...

hhh 4y ago

I wouldn't have discovered the site if not for this handbook. Pretty cool way to find new art.

xwowsersx 4y ago

I really admire the organization and clarity of this documentation. I'm going to take a lot of inspiration from this. Good work.

maliker 4y ago

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.

procarch2019 4y ago
John? 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.
- maliker 4y ago
  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.
  - procarch2019 4y ago
    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)
- leetrout 4y ago
  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+
  - procarch2019 4y ago
    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.

maroonblazer 4y ago

I'd love to know the background of how something this comprehensive is created and maintained. Was this the work of one person? A team? Was it created in one go or did it start small and evolve? Very impressive!

alexeldeib 4y ago
Probably helps that the first suggestion is to PR the README :) More seriously, I agree. Reading this doc, the values, etc, make me want to work for this company I’d never heard of before.
dblock 4y ago
(I was CTO of Artsy then.) 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. More practically, check out https://github.com/artsy/meta/pull/1 https://github.com/artsy/meta/pull/1, which is one of the repos that merged into the handbook via https://github.com/artsy/README/pull/1 https://github.com/artsy/README/pull/1. Also note that Artsy was founded in 2010. This handbook in its current iteration is 7-8 years in, but its content goes back to ~2011 in some kind of evolution. You'll want to check out https://artsy.github.io/blog/archives/ https://artsy.github.io/blog/archives/ as well.
- stakhanov 4y ago
  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?
  - orta 4y ago
    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 - (the making of artsy/README) https://artsy.github.io/blog/2018/08/21/OSS-by-Default-Docs/ https://artsy.github.io/blog/2018/08/21/OSS-by-Default-Docs/ - (OSSing our apps) https://artsy.github.io/blog/2019/04/29/how-did-artsy-become-oss-by-default/ https://artsy.github.io/blog/2019/04/29/how-did-artsy-become... - (OPs writeup on the philosophy) https://code.dblock.org/2015/02/09/becoming-open-source-by-default.html https://code.dblock.org/2015/02/09/becoming-open-source-by-d... - (the RFC process) https://artsy.github.io/blog/2019/04/11/on-an-rfcs-process/ https://artsy.github.io/blog/2019/04/11/on-an-rfcs-process/

TruthWillHurt 4y ago

Amazing how you keep updating it

stefap2 4y ago

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.

orta 4y ago
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.

brainbicycle 4y ago

:disclaimer I work at Artsy: cool to see this on the front page! If this interests you be sure to check out the artsy org on github: https://github.com/artsy https://github.com/artsy 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. The blog and podcast may also be of interest: https://artsy.github.io/open-source/ https://artsy.github.io/open-source/ https://podcasts.apple.com/us/podcast/artsy-engineering-radio/id1545870104 https://podcasts.apple.com/us/podcast/artsy-engineering-radi...

deleted 4y ago
[deleted]
talhachy 4y ago
Can you tell me if the product part is mistakenly locked or is there any way I could get access to the resource?: https://github.com/artsy/README#:~:text=in%20the%20Product,%F0%9F%94%91 https://github.com/artsy/README#:~:text=in%20the%20Product,%...
- pvinis 4y ago
  links with the key emoji next to it are private. 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.

nonethewiser 4y ago

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.

deleted 4y ago
[deleted]
- deleted 4y ago
  [deleted]
stakhanov 4y ago
I'm tentatively with you. 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.

poyes99680 4y ago

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 https://github.com/artsy/README/issues/459 - starting a 3 full-day hackathon every quarter. https://github.com/artsy/README/issues/441 https://github.com/artsy/README/issues/441 - 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 https://github.com/artsy/README/issues/427

aba30 4y ago
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.
- tkiolp4 4y ago
  Hackathons are (if any) for people in their 20s with no family/kids. For me companies doing hackathons is a red flag.
  - statusgraph 4y ago
    Company hackathons are rarely 24hr affairs and more "don't do your normal work during working hours"
    - deleted 4y ago
      [deleted]
  - dblock 4y ago
    My daughter (second child) was born 4 days after I started at Artsy. Some of the best new ideas came from hackathons.

ArtWomb 4y ago

>>> NYC Mobile Forum ??? Like Brecht Forum? Is there a space to revive this weekly convening ;)