최고의 개발자 경험을 구축하기 위한 5가지 팁 (번역)

원본: https://betterprogramming.pub/5-tips-for-building-the-best-developer-experience-possible-879777ffc9d4

5 Tips for Building the Best Developer Experience Possible

개발자 경험은 소프트웨어에서 빼놓을 수 없는 부분입니다. 좋으면 좋은 거죠. 나쁘면... 모두들 이야기만 하고 아무도 사용하지 않습니다.

2022년 5월, 저는 Postman의 고객 서밋에 초대되어 업계 리더들과 API에 대해 이야기를 나누었습니다. 그곳에서 저는 패널로 참석하여 개발자 경험(DX)에 대해 이야기해 달라는 요청을 받았습니다. 개발자 경험은 제가 경험해본 적이 없는 분야였기 때문에 조금 당황스러웠습니다. 모든 서밋 참석자들 앞에서 무언가 허공에서 무언가를 끌어낼 수 있으리라 마음속으로 기대하며 마지못해 동의했습니다.

놀랍게도 저는 이 주제에 대해 매우 의견이 많았습니다. 알고 보니 개발 관리자로 일하면서 써드파티 API를 많이 접한 덕분에 '좋은 개발자 경험이란 무엇인가'에 대한 강한 감각이 생겼기 때문입니다. 휴!

최근 Ready, Set, Cloud 팟캐스트 에피소드 3에서 더 나은 개발자 환경을 구축하는 방법에 대해 Lars Jacobsson과 이야기할 수 있는 기회를 가졌습니다. 무엇보다도 좋은 DX는 다음과 같은 결론을 내렸습니다

• 개발자 생산성 향상
• 소비자에게 새로운 기능 노출
• 사용자가 계속 사용하도록 장려

Lars와 저는 이러한 점을 좋은 DX의 주요 동인으로 논의했지만, API, SDK 또는 서비스가 이러한 기능을 수행하도록 만드는 방법에 대해서는 이야기하지 않았습니다. 좋은 DX를 구성하는 요소를 아는 것과 주요 동인을 구축(및 실행)하는 방법을 아는 것은 완전히 다른 문제입니다.

제가 직접 경험하면서 터득한 최고의 DX를 구축하는 방법에 대한 5가지 팁을 소개합니다.

1. 스토리의 힘을 활용하여 모든 것을 문서화

개발자가 싫어하는 두 가지가 있습니다. 문서 작성 과 단위 테스트 빌드입니다 . 그러나 진실은 두 가지 모두 프로덕션 애플리케이션의 장기적인 성공에 필요하고 결정적이라는 것입니다.

문서를 2등 시민으로 취급하는 API, 프레임워크 및 플랫폼을 몇 번이고 보게 됩니다. 때로는 문서가 코드에서 생성되고 때로는 손으로 작성됩니다. 그러나 문서가 우선 순위로 지정되지 않은 경우 항상 알 수 있습니다. 오래되었거나 맥락이 부족하거나 의미 있는 예가 없을 수 있습니다.

문서화는 좋은 인상을 남길 수 있는 첫 번째 기회입니다.

그들이 첫인상에 대해 뭐라고 하는지 알아? 당신은 하나만 얻습니다. 많은 개발자가 문서의 첫 페이지를 읽고 처음 30초 안에 앱을 사용할지 여부를 결정할 것입니다 . 생성되거나 복잡한 문서는 잠재적인 신규 소비자를 설득하지 못합니다. 독자를 사로잡고 시도하도록 설득하는 매력적인 문서를 작성해야 합니다.

몇 년 전(지금까지!) 저는 은유를 사용하여 기술 분야에서 스토리를 구축하는 방법 에 대해 썼습니다 . 공감할 수 있는 방식으로 아이디어를 표현할 수 있다면 더 많은 청중에게 도달하고 감정적인 수준에서 연결됩니다. 계속해서 찾아오는 이야기나 공감할 수 있는 참고 자료를 만들 수 있다면 소비자는 더 참여하고 제품을 이해하고 사용해 볼 가능성이 훨씬 더 높아질 것입니다.

Momento 의 컬렉션 데이터 유형에 대한 내 릴리스 노트 블로그를 예로 들어 보겠습니다 . 이 게시물에서는 새로운 방식으로 캐시하고 상호 작용할 수 있는 세 가지 새로운 데이터 유형에 대해 설명합니다. 그 자체로는 가장 흥미로운 주제가 아닙니다.

하지만 이 글 전체에서 저는 도토리 사냥이라는 가상의 게임을 만드는 것에 대해 이야기합니다. 재미있는 예시와 관련된 의미 있는 사용 사례를 제공하고 전체 릴리스를 하나로 연결합니다. 이 게시물은 모두가 게임을 하고 있거나 해본 경험이 있기 때문에 재미있고 활기차며 공감할 수 있습니다. 전반적으로 경쾌한 어조로 글을 작성하면 독자가 릴리스의 주요 내용을 파악하고 세부 사항을 이해하기 위해 대충 훑어보지 않고 끝까지 읽을 가능성이 훨씬 더 높습니다.

문서로 이렇게 하세요! 잠재 고객이 제공해야 하는 기능에 대해 계속 관심을 갖고 읽을 수 있도록 내러티브를 구축하세요. 독자가 공감할 수 있는 참고 자료는 이해도를 높이고 궁극적으로 사용해 볼 가능성을 높입니다.

 

2. 오래된 문서는 사람을 즉시 잃게 합니다.

저는 최근에 뉴스레터 플랫폼을 구축하여 주간 뉴스레터인 금주의 서버리스 추천을 발송하고 있습니다.

솔루션의 일부는 이메일 제공업체 SendGrid와 통합하는 것이었습니다. 2019년 초에 트윌리오가 센드그리드를 인수하면서 통합을 구축할 수 있게 되어 기뻤습니다. 저는 종종 트윌리오를 DX와 관련하여 최고라고 생각해왔습니다. 문서가 훌륭하고, 사이트에서 의미 있고 비즈니스에 초점을 맞춘 사용 사례를 제공하며, 모든 것이 잘 작동하는 경향이 있습니다. 그래서 인수 후 4년이 지났기 때문에 당연히 SendGrid도 이 정도일 거라고 생각했습니다.

제가 틀렸습니다.

문서가 트윌리오와 비슷한 느낌이었지만, 그게 거의 유일한 겹침이었습니다. 사이트에서 제공되는 문서가 부정확하고 설명이 오래된 경우도 있었습니다. 엔드포인트에 정의된 속성이 존재하지 않거나 데이터 유형이 완전히 틀린 경우도 있었습니다.

이러한 문제를 천천히, 그러나 확실하게 해결할 수 있었습니다. 하지만 API에 대한 신뢰감을 심어주지는 못했습니다!

첫 번째 잘못된 문서를 발견하자마자 나머지 문서도 의심하기 시작했습니다. 무엇이 효과가 있고 무엇이 효과가 없는지 어떻게 알 수 있을까요? 제가 찾은 것은 일회성인가요? 어떻게, 왜 잘못된 것인지 알 수 있는 방법이 없었고, SendGrid의 누군가를 찾아서 설명해 줄 생각도 없었습니다.

이 교훈을 통해 최신 문서가 얼마나 중요한지 알 수 있습니다.

문서화는 API 참조에서 그치지 않습니다! 코드가 어떻게 작동하는지 설명하기 위해 사용하는 예제는 문서 자체만큼, 아니 그 이상으로 중요합니다. 얼마 전 새로운 패키지를 살펴보던 중 npm의 예제를 로컬에 있는 스크립트에 복사하여 사용해 보았습니다.

실망스럽게도 예제는 작동하지 않았습니다! 문서에 있는 내용을 그대로 복사했지만 실행했을 때 런타임 오류가 발생했습니다. 저는 이 패키지를 직접 만들지 않았기 때문에 문제를 해결하는 방법을 전혀 몰랐습니다. 더 잘 지원된다는 인상을 주는 다른 패키지를 찾아서 재빨리 포기했습니다.

이 모든 것을 말하자면, 문서화를 최우선 과제로 삼으시기 바랍니다!

 

3. 근본주의는 개발자 경험을 죽입니다

근본주의는 새로운 것을 배울 때 유용합니다. 근본주의란 책에 명시된 대로 엄격하게 행동하는 것을 의미합니다. 규칙을 정해진 대로 정확하게 따르고 규칙을 어기는 것에 관대하지 않습니다.

이보다 더 좋은 학습 방법은 생각할 수 없습니다. ‘내 마음대로’ 하지 않고 정해진 범위 안에 머무르면 주제나 개념의 핵심을 확실히 이해할 수 있습니다.

그렇긴 하지만 근본주의자가 되지 말라는 말을 몇 번 인용한 적이 있습니다.

개발자의 경험을 위해 구축할 때는 근본주의가 통하지 않습니다. 가능한 경우 지름길을 택하세요. 예를 들어 REST API는 생성, 업데이트, 읽기 및 삭제 방법에 대한 엄격한 규칙이 있는 엔티티 기반 액세스 메커니즘입니다. 하지만 개발자의 삶을 최대한 쉽게 만드는 것을 목표로 하는 API를 구축하는 경우에는 몇 가지 작업을 결합하는 것이 합리적일 수 있습니다.

뉴스레터를 생성하는 API가 있는 경우 POST /newsletters, POST /newsletters/{id}/subscribers, PUT /newsletters/{id}/profile에 대한 별도의 엔드포인트를 만드는 대신 모든 작업을 한 번에 수행하는 단일 엔드포인트인 POST /import-newsletter를 만들 수 있습니다. 단일 엔드포인트는 뉴스레터 생성, 구독자 추가, 프로필 정보 설정 등 세 가지 작업을 모두 수행하지만 호출자는 API를 한 번만 호출하면 됩니다. 호출자를 대신하여 오케스트레이션을 수행하고 문제가 발생할 경우 오류, 재시도 및 롤백을 관리하기 때문에 더 나은 경험을 제공합니다.

소프트웨어는 트레이드오프에 관한 것입니다. 소비자의 사용 편의성에 유리한 것을 선택해야 합니다.

기능을 하나로 결합하면 소비자에게 이전에 사용하지 않았던 새로운 기능을 소개할 수 있습니다. 이미 사용하고 있는 기능에 새로운 기능을 통합하여 새로운 기능을 사용해 볼 수 있는 간단한 방법을 제공하세요. 진입 장벽이 낮을수록 사용률이 높아집니다.

4. 고객이 있는 곳에서 고객을 만나세요

최근에 여러 가지 프로그래밍 언어로 SDK를 구축하는 것에 대해 논의하는 회의에 참석했습니다. SDK는 동일한 API를 래핑하지만 Go, Python, Java, .NET, Node.js와 같은 언어로만 사용할 수 있습니다.

저희의 초기 생각은 이러한 SDK를 각각의 언어로 작성되었을 뿐 완전히 동일하게 만드는 것이었습니다. 동일한 함수 이름, 동일한 입력, 동일한 출력. 하지만 그렇게 하면 특정 프로그래밍 언어에 맞지 않는 이상한 경험이 발생할 수 있었습니다.

예를 들어, SDK 클라이언트가 .NET 사용자에 최적화되어 있다면 JavaScript 사용자에게는 너무 장황하고 구조적으로 느껴질 수 있습니다. 클라이언트를 초기화하고 사용하는 데 너무 많은 노력이 필요하다고 느껴진다면 표준 자바스크립트 개발자는 금방 포기할 것입니다(적어도 저라면 그럴 것입니다).

이를 염두에 두고 저희는 SDK를 '드리프트’하자는 이야기를 시작했습니다. 개발자가 각 프로그래밍 언어에서 익숙한 환경에 가장 잘 맞도록 API 호출의 입력과 출력을 변경하는 것입니다. .NET 클라이언트의 모든 컴포넌트를 강력하게 유형화하고 분리합니다. 자바스크립트로 빠르게 움직이고 유연하게 대처하세요. 이해가 되시겠죠?

어차피 한 명의 개발자가 동일한 SDK를 다른 언어로 사용할 가능성은 낮습니다. 개발자 경험을 만족스럽게 유지하려면 개발자의 행동에 맞게 최적화해야 합니다.

가능한 한 진입 장벽을 낮추고 싶을 것입니다. 전반적인 경험을 더 쉽고 친숙하게 만들수록 소비자의 만족도가 높아집니다. 소비자가 만족할수록 더 많이 사용하고 친구들과 공유할 가능성도 높아집니다.

5. 관찰 가능한 경험 제공

저는 올해 작성한 모든 블로그 게시물에서 통합 가시성을 강조해야 한다고 언급했습니다. 그렇다면 이것이 개발자 경험에 어떤 의미가 있을까요?

이 경우에는 백엔드에 도구를 추가하여 KPI를 추적하는 방법에 대해 이야기하는 것이 아닙니다. 소비자가 서비스 사용 현황을 한눈에 파악할 수 있는 기능을 말하는 것입니다. 얼마나 소비하고 있나요? 누가 어떤 기능을 사용하고 있나요? 대시보드를 통해 사용자에게 액세스 권한을 부여하거나 취소할 수 있나요?

이러한 기능은 종종 _제어 영역_에 있습니다. 대시보드를 '관리 대시보드’라고 부르기도 하지만, 궁극적으로는 데이터 요청을 중앙에서 쉽게 액세스하고 제어할 수 있는 방법을 제공하는 것이 목적입니다. 예를 들어, SQS용 AWS 콘솔을 생각해 보겠습니다.

대기열을 만들고, 업데이트하고, 삭제할 수 있는 대시보드가 있습니다. 대기열 트리거를 설정하거나 항목을 삭제할 수 있습니다. 생성 날짜, 사용 가능한 메시지 수, 암호화 설정과 같은 일부 메타데이터도 확인할 수 있습니다. 이러한 기능은 모두 컨트롤 플레인 기능입니다. 데이터를 구동하는 작업을 제어합니다. 서비스에 꼭 필요한 기능입니다!

사용량에 대한 가시성을 추가하면 사용자에게 편안함을 제공합니다. 월말에 청구서가 날아올 때 예상치 못한 금액이 청구되지 않을 것이라는 사실을 알 수 있기 때문입니다. 이와 같은 관리 뷰가 소비자의 비즈니스 문제를 해결해 주지는 못하지만, 사용량에 대한 귀중한 통계를 제공합니다.

요약

개발자 경험이 중요합니다! 시장에서 최고의 제품을 보유하고 있어도 DX가 좋지 않으면 채택에 어려움을 겪을 수 있습니다.

AWS Step Functions이 이에 대한 완벽한 예입니다. 이 팀은 사용자가 브라우저에서 워크플로 단계를 드래그 앤 드롭할 수 있는 놀라운 사용자 인터페이스인 워크플로 스튜디오를 구축했지만, 로컬 asl 파일과 통합되지는 않습니다. 브라우저에서 정의를 가져와서 코드를 수동으로 업데이트해야 하며, 매번 적절한 정의 대체를 추가해야 합니다.

워크플로우 스튜디오의 경험은 놀랍습니다. 제게는 AWS 콘솔 중 단연 최고의 경험입니다. 하지만 로컬 asl 파일에 수동으로 코드를 복사해야 하는 불편한 경험 때문에 사람들은 운영상의 이점이 있음에도 불구하고 사용을 미루고 대신 람다 함수를 사용하는 것을 선택하게 됩니다.

개발자 경험을 처음부터 끝까지 생각해 보세요. 어느 한 부분만 훌륭하게 만들고 나머지는 무시하는 것이 아닙니다. 전체 서비스를 사용하기 쉽고 직관적으로 만드는 것이 중요합니다. 새로운 기능을 발견할 수 있도록 지원하는 것입니다. 작은 관련 명령어를 결합하여 API 호출의 성능을 향상시킴으로써 개발자의 삶을 더 편리하게 만드는 것입니다.

문서는 서비스의 관문입니다. 문서가 오래되었거나 부정확하거나 제대로 작성되지 않았다면 개발자가 서비스를 사용해 보도록 설득할 수 없습니다. 깔끔하고, 비즈니스 프로세스를 따르고, 제대로 작동하는지 확인하세요! 영감을 얻고 싶다면 Stripe와 Twilio보다 더 좋은 개발자 문서를 본 적이 없습니다. 그들처럼 되세요!

SaaS를 구축하는 것은 비즈니스 문제를 해결하는 것 그 이상입니다. SaaS 제공업체로서 우리는 서비스를 기반으로 구축할 때 소비자에게 풍부한 경험을 제공해야 할 의무가 있습니다. 레고 세트를 조립할 때 설명서가 틀렸거나 누락되었다고 상상해 보세요. 또는 설명서는 정확하지만 NASA 엔지니어를 타깃으로 작성된 것일 수도 있습니다. 아이들은 조립에 성공하지 못할 것입니다.

고객이 있는 곳에서 고객을 만나세요. 그들을 위해 빌드하세요. 의미 있고 최신의 문서를 제공하여 시작하도록 하세요. 성공할 수 있는 도구를 제공하세요.

즐거운 코딩이 되세요!