자료 화면 타이틀은 "WHY DON'T WE JUST GET AI TO WRITE THE DOCS?"입니다.
발표자는 호주에서 Shippit이라는 multi-carrier shipping software 기업에 24년 2월 합류했습니다. 그전에는 테크니컬 라이터가 없었고 각 업무 담당자가 문서를 작성했습니다. 이렇게 작성된 문서가 꽤 많았죠. 내용도 적절했습니다. 하지만 2가지 문제가 있었습니다.
- 각 문서의 내용은 적절했지만 구성이 제각각이었고
- 사용자에게 필요한 일부 문서는 내부 시스템에서만 관리되고 있었습니다.
그래서 필요한 것은
- 콘텐츠를 모아서(Get all the content together)
- 사용자가 쉽게 찾을 수 있고(Where developers could find it)
- 바로 적용할 수 있고(In a format they can use)
- 서로 다른 콘텐츠들과 어울리는 형태로(In a way that fit with our other content)
제공하는 것이었습니다.
이 작업을 위해 LLM을 사용하기로 했습니다.
- API 문서를 모두 PDF 파일로 내려받아 LLM에 업로드했습니다.
- API와 관련된 관련 문서를 PDF 파일로 내려받아 LLM에 업로드했습니다.
- 내부 시스템에서만 관리되는 문서는 혹시 고객의 실제 데이터가 포함되어 있을 수 있는데 이를 검토할 시간이 부족해 이번 프로젝트에서는 제외했습니다.
그리고 각 문서에 대해 질의를 시작했습니다.
먼저 API 문서의 내용을 파악하고 요약하는 것입니다.
I'm uploading a copy of our API documentation. Can you give me a summary of what you see in this file? Focus on what the API does, how it works, and what kinds of things you can do using this API.
API 문서를 업로드했습니다. 이 파일의 내용을 요약해 주시겠어요? API의 기능, 작동 방식 및 이 API를 사용하여 수행할 수 있는 작업의 종류에 중점을 두세요.
그리고 API 관련된 추가 문서를 앞에서 추출한 내용에 추가하는 것입니다.
I'm going to upload some more documents about our API, can you use these documents, and tearite your response above with the additional information.
API에 대한 문서를 몇 개 더 업로드했는데, 이 문서를 사용해 주시고 위의 답변에 추가 정보를 첨부해 주세요.
마지막으로 API문서, 관련 문서를 기반으로 새로운 개발자 가이드를 만드는 것입니다.
If you were to write a Developer Guide to accompany this API, what structure would you use for the document? The document does not need to include specific information about the individual endpoints, because that is included in the accompanying API documentation, but it should include information about how to use the API, how to authenticate, and how to place orders. It should also have clear sections for troubleshooting, and provide lots of worked examples and code samples. Provide an table of contents for the document, and any additional comments you would like to make.
이 API와 함께 개발자 가이드를 작성한다면 문서에 어떤 구조를 사용하겠는가? 개별 엔드포인트에 대한 구체적인 정보는 함께 제공되는 API 문서에 포함되어 있으므로 문서에 포함할 필요는 없지만 API 사용 방법, 인증 방법, 주문 방법에 대한 정보는 포함되어야 합니다. 또한 문제 해결을 위한 명확한 섹션이 있어야 하며, 많은 작업 예제와 코드 샘플을 제공해야 합니다. 문서에 대한 목차와 추가 의견을 제공하세요.
(중간에 영상이 일부 끊기는데, 아마 데모 영상이었던 것 같구요. 공개하기 애매한 부분이었나 봅니다).
기본적으로는 Gemini Advanced(유료)를 사용했다고 합니다.
추가로 몇 가지 도구를 더 소개했는데요. widdershins은 OpenAPI를 마크다운으로 변환해 주는 도구입니다.
https://github.com/Mermade/widdershins
이렇게 변환된 마크다운 파일을 기능 단위로 나누려고 했는데 잘 되지 않았다고 합니다.
I'm going to upload a file that contains a lot of schemas for an API in markdown format. I want you to split the file up into smaller files, each file should contain all the schemas that pertain to their functional zelationships. For example, all the schemas pertaining to OrderRequest should go in one file, with all the schemas pertaining to TrackingResponse in another.
API에 대한 많은 스키마가 포함된 파일을 마크다운 형식으로 업로드하려고 합니다. 파일을 더 작은 파일로 나누고 각 파일에는 기능적 관계에 관련된 모든 스키마가 포함되어야 합니다. 예를 들어 주문 요청과 관련된 모든 스키마는 한 파일에, 추적 응답과 관련된 모든 스키마는 다른 파일에 넣어야 합니다.
그래서 VSCode에서 copilot을 사용해 원하는 결과를 얻었습니다.
Find all the schomas that relate to OrderRequestOrder
Find all the schemas that relate to OrderRequestOrderParcelAttributes
Find all the schemas that relate to Product (and so on)
OrderRequestOrder과 관련된 모든 스키마 찾기
OrderRequestOrderParcelAttributes과 관련된 모든 스키마를 찾습니다.
Product와 관련된 모든 스키마 찾기(등)
이런 식으로 LLM의 도움을 받아 문서를 작성했는데 실제 결과물에서는 많은 내용이 누락된 것이 발견되었고 이는 계속 수작업으로 수정하고 있습니다.
그럼에도 AI를 활용하는 것은 꽤 많은 도움이 됩니다.
- Starting point: 처음부터 모든 것을 직접 작성하지 않고 어느 정도 초안을 자동 생성한 후 편집할 수 있습니다.
- Boring stuff: 지루한 반복 작업에 유용합니다만 잘 구성하지 않으면 소용이 없습니다(완전하게 규칙을 뽑아낼 수 없다면 직접 확인을 해야 합니다).
- Summarising: 정보를 정리하고 이해하는데 좋습니다.
- Inconsistency: 어느 정도 잘 되기도 하고 안되기도 합니다.
Q&A에서 실제로는 업무를 진행하면서 이런 변환 작업보다는 콘텐츠를 이해하는데 AI를 많이 활용한다고 합니다. 예를 들어 전문적인 용어에 대해 이해하고 이를 더 일반적인 용어로 어떻게 설명할 수 있는지 예전보다 쉽게 확인할 수 있다고 합니다. 테크니컬 라이터들이 가지고 있는 두려움(질문에 대한)을 어느 정도 해소시켜 줄 수 있는 부분이기도 하네요(물론 그 내용을 신뢰할 수 있는지는 다른 문제지만).
https://youtu.be/e-uY1_JanKc?si=2upQwLpxBcWpdYxv
Write The Docs 2025 - Lana Brindley
www.flickr.com
