전체 글
-
[우아한 테크 세미나] "개발자도 글을 잘 써야 한다고요?" 테크 세미나 요약과 느낀점Technical Writing/Technical Writer 2022. 7. 29. 19:00
아직까지는 국내에 테크니컬 라이팅에 대한 인지도나 강의 등이 외국에 비해서 덜하다고 생각했습니다. 하지만 최근에 한겨레 교육센터에서도 테크니컬 라이팅 교육을 진행하고 채용 공고도 2-3년 전에 비해서 많이 증가했다고 느끼고는 합니다. 직무 관련해서 아직 궁금한 게 너무 많은데 국내에서는 강의를 많이 진행하지도 않고 아쉬워서 구글 테크니컬 라이팅 관련 세션에 참여를 했었던 적이 있었습니다. 하지만 영어 진행 + 시차로 인해서 새벽에 진행돼 다소 힘들었던 기억이 납니다... 오늘도 여기저기 글들을 읽어보던 중 배민에서 '개발자도 글을 잘 써야 한다고요?'라는 라이브를 진행한다는 것을 알게 되었습니다. 얼마 전 배민에서 테크니컬 라이팅 코치를 채용하는 공고를 본 적이 있는데 개발자를 위한 글쓰기 등의 책을 쓰..
-
API 문서화 공부하기 - 8 깃북과 마크다운으로 API 문서 정리하기API 2022. 7. 11. 20:41
1 - 7 포스팅을 통해 API에 대해서 공부해보았다. 공부한 내용을 바탕으로 작성한 Surfreport 예시를 이미 익숙한 툴인 깃북과 마크다운 문법으로 정리해보려고 한다. API가이드를 작성할 때 자주 사용되는 툴로는 Swagger와 앞서 잠깐 살펴보았던 Postman도 있다. 아직 본격적으로 사용해보지는 않았지만 API에 대해서 공부하면서 언젠가 사용해볼 기회가 있지 않을까?_? gitbook 먼저 깃북에서는 API를 작성할 수 있는 블록을 제공한다. API Method를 클릭하면 아래와 같은 블록이 생성된다. 이 블록에 입력 값을 입력만 해주면 이제까지 봤던 API문서의 형태로 정리할 수 있다. 요새 깃북을 사용해보고 있어서 깃북을 통해 정리해보려고 했다. 하지만 깃북을 사용하다 보니 다른 툴을 ..
-
API 문서화 공부하기 7 - 응답 예제와 응답 스키마API 2022. 6. 30. 22:49
이사 준비로 어영부영 6월이 지나갔다. 이사를 무사히 마쳤으니 다시 열심히 포스팅해야겠다! 😁 응답 예제와 응답 스키마 응답 예제는 요청 예제의 샘플 응답을 보여준다. 응답 예제는 모든 매개변수를 포괄하지는 않지만 요청 예제에서 전달된 매개변수와 일치해야 한다. 응답을 통해 개발자는 리소스에 원하는 정보, 형식 및 해당 정보가 구조화되고 레이블이 지정되는 방식이 무엇인지 알 수 있다. 응답에 대한 설명을 응답 스키마라고 한다. 응답 스키마는 반환될 수 있는 각 속성, 각 속성에 포함된 내용, 값의 데이터 형식, 구조 및 기타 세부 정보를 나열하여 보다 포괄적인 방식으로 응답을 문서화한다. 응답 스키마 살펴보기 응답 예제와 응답 스키마의 차이는 무엇일까? 응답 예제는 요청 예제와 일치해야 한다. 요청 예제..
-
API 문서화 공부하기 6 - 요청 예시API 2022. 6. 2. 20:16
요청 예시 살펴보기 요청 예시에는 엔드포인트를 사용하는 샘플 요청이 포함되어 있으며 일부 매개변수를 보여준다. 요청 예제는 모든 매개변수를 표시하지는 않지만 매개변수를 가능한 많이 보여주는 것이 좋다. 지난번 살펴본 토스페이 API 가이드에서는 오른쪽에 샘플 요청과 응답을 보여주고 있다. 다양한 언어들로 요청 예제를 제공하고 있지만 위 예시는 curl 형식의 예제이다. 일반적으로 curl을 사용하여 샘플 요청을 표시한다. curl은 요청에 필요한 헤더 정보와 요청과 함께 사용된 방법을 보여준다. ✋curl이란? 다양한 매개변수와 메서드를 사용하여 HTTP 요청을 실행할 수 있는 command line이다. curl을 사용할 때는 curl입력 후에 다음에 출력을 받아올 URL을 추가하여 작성한다. HTTP..
-
API 문서화 공부하기 5 - 매개변수API 2022. 5. 25. 21:13
매개변수 예시 살펴보기 매개변수(Parameter)는 엔드포인트와 함께 전달할 수 있는 옵션이다. 헤더 매개변수, 경로 매개변수 및 쿼리 문자열 매개변수와 같은 여러 유형의 매개변수가 있다. 매개변수의 예시는 다음과 같다. 토스 페이먼츠에서는 문서 옆에 코드 예제를 같이 보여주기 때문에 표를 더 간단하게 작성한 것 같다. Type이나 Required 열을 별도로 두지 않고 parameter name 아래에 같이 작성한 것을 확인할 수 있다. API문서에서 매개변수들은 대부분 아래 표 형태에서 크게 벗어나지 않는다. Parameter Required/Optional Description Data Type format Optional - String 문서 작성 시 주의해야 할 사항 매개변수 유형에 관계없이 ..
-
API 문서화 공부하기 4 - 엔드포인트와 메서드API 2022. 5. 18. 19:51
엔드포인트(Endpoint)는 리소스에 액세스 하는 방법을 의미하고 메서드(Method)는 리소스와의 상호작용을 의미한다. 동일한 리소스에는 일반적으로 경로와 메서드가 다르지만 동일한 리소스에 대해 다른 정보를 반환하는 엔드포인트가 있다. 엔드포인트에는 "API 문서화 공부하기 3"에서 다루었던 리소스 설명과 유사하지만 간단한 설명이 존재한다. 또한 엔드포인트에는 모든 엔드포인트의 기본 경로가 아니라 리소스 URL의 마지막 경로만 표시된다. 엔드포인트 예시 아래 이미지는 토스페이 결제 상태 확인에 대한 엔드포인트 예시이다. API 문서의 대부분은 엔드포인트를 중심으로 작성되기 때문에 엔드포인트는 문서에서 강조 효과를 주는 방식으로 작성되어 있는 경우가 많다. 엔드포인트는 개발자가 요청을 수행하기 위해 구..
-
API 문서화 공부하기 3 - REST API 문서 섹션과 리소스 설명API 2022. 5. 11. 20:49
API문서 작성을 하는 테크니컬 라이터는 문서 프로젝트를 처음부터 시작하지는 않는다. 내부 위키 페이지에 있는 정보들을 활용해서 가공해야 한다. 대부분 이 문서들은 팀 내부에 있는 엔지니어들만 알아볼 수 있는 내용들과 정리되지 않은 내용들로 이루어져 있다. 테크니컬 라이터는 이 정보를 사용자가 알아볼 수 있는 정보로 바꾸는 역할을 수행한다. API 문서를 작성해보는 실습을 하기 위해서 공부를 하고 있는 사이트에서 가상의 위키 페이지를 제공해주었다. Surfreport API에 대한 위키 페이지이다. (이런 식으로 가공되지 않은 정보들이 올라온다는 말인 걸까? 실제로 IT회사에서 근무해보지는 않아서 모르겠다.🙄) 보다시피 예제로 제공된 위키 페이지는 정보가 구조화되어있지 않고 사용자가 원하는 정보를 한눈에..
-
API 문서화 공부하기 2 - API 호출하기, JSON 규칙API 2022. 5. 9. 21:07
API 문서를 작성해보기 전에 실제 REST API를 사용해서 REST API에 대해서 이해하고 개발자가 어떤 작업을 수행하는지 알아볼 수 있다. 여기서 사용하는 툴은 ATOM과 Postman이다. https://openweathermap.org/ Сurrent weather and forecast - OpenWeatherMap Leaving everything behind, people are fleeing conflict in Ukraine. They need shelter, food, and water. When you subscribe to our service, you can join us to help with donation of just of 20. Openweather will add 4..