7월 7일
Docusaurus를 이용한 API 문서 플랫폼의 진화
https://d2.naver.com/helloworld/6196427
네이버 사내 기술 교류 행사인 NAVER ENGINEERING DAY 2025(5월)에서 발표되었던 세션이라고 합니다. 그래서 문서의 작성보다는 기술적으로 기존 문서화 플랫폼(Redoc)에서 새로운 플랫폼(Docusaurus)으로 전환하는 과정, 검색 기능(typesense)을 추가하는 과정, 버전에 따른 안정적이 배포 방식(Nubes) 등을 설명합니다.
기존에는 Redoc 커뮤니티 버전을 사용하고 있었는데, 버그도 많고 앞으로 추가하려는 기능 제약, 성능 이슈 등의 문제로 좀 더 컨트롤이 가능한 오픈소스 문서화 플랫폼을 찾았고, Docusaurus를 선택했다고 합니다.
* 라인에서도 최근 도큐사우르스를 어떻게 활용하고 있는지 공개한 적이 있습니다.
https://techblog.lycorp.co.jp/ko/docusaurus-as-a-technical-document-website
* 현대차 개발자 센터에서도 관련 기술 블로그 글이 올라오긴 했는데, 실제 적용을 했는지는 모르겠네요.
https://developers.hyundaimotorgroup.com/blog/159
하여간, 관련 세션에서 언급한 사이트들은 아래와 같습니다. Nubes의 경우에는 네이버 사내에서 사용하는 objectStorage 이름이 아닌가 싶습니다. 2021년 컨퍼런스에서 언급된 적이 있는데 네이버 클라우드 사이트에서는 해당 이름을 찾을 수가 없네요.
네이버 커머스 API 센터
https://apicenter.commerce.naver.com/ko/basic/main
https://apicenter.commerce.naver.com/docs/commerce-api/current
Redoc(문서화 플랫폼)
https://redocly.com/redoc
https://github.com/Redocly/redoc
https://redocly.com/pricing
Docusarus(문서화 플랫폼)
https://docusaurus.io/
https://github.com/PaloAltoNetworks/docusaurus-openapi-docs
https://infima.dev/
typesense(검색)
https://typesense.org/
https://www.algolia.com/
https://github.com/algolia/docsearch
https://github.com/typesense/typesense-docsearch.js
https://github.com/typesense/typesense-docsearch-scraper
https://github.com/typesense/docusaurus-theme-search-typesense
Nubes(배포)
https://www.ncloud.com/product/storage/objectStorage
https://nginx.org/
https://airflow.apache.org/
7월 10일
LLM 시대의 글쓰기
https://news.hada.io/topic?id=21909
얼마 전 구글에서 진행한 행사에 참석했던 누군가가 발표 자료를 보면서 AI가 만든 느낌을 강하게 받았다는 언급을 했었는데, 그런 느낌을 받는 분들이 많은가 봅니다. 저도 가끔 이해가 안 되는 내용은 AI의 도움을 받곤 하는데(도움이라고 하지만 복붙에 가까운) 반성하게 되네요.
원문은 https://www.sh-reya.com/blog/ai-writing/ 입니다. 글쓴이는 메타와 구글의 AI 관련 연구에 참여하고 있는 박사과정 5년 차라고 합니다.
7월 11일
개발자의 문장력: 협업을 살리는 소프트 스킬의 힘
https://okky.kr/events/webinars/1537740
7월 29일(화요일) 저녁에 진행되는 유료 세미나입니다.
CJ올리브영 DevRel Specialist 최가인 님의 강연입니다.
7월 14일
TW pet peeves: display versus appear
https://www.reddit.com/r/technicalwriting/comments/1lunidf/tw_pet_peeves_display_versus_appear/
동사의 사용에 대해 민감한 분들이 있죠. 이번 글도 그런 논쟁입니다. 꽤 많은 댓글이 달려 있으니 같이 보시면 좋을 것 같네요.
마이크로소프트 스타일 가이드에서는 2019년 이전에는 appear를 사용하도록 권장했는데, 더 이상 권장하지 않는 것으로 변경되었다고 합니다. 상황에 따라 문서 작성자가 적절한 표현을 사용해야 한다는 이야기입니다. 예를 들어 UI 요소 내에 display라는 명칭이 있다면(좋은 UI는 아니지만), 동사로서 display를 사용할 때 사용자가 혼란스러울 수도 있구요.
https://learn.microsoft.com/en-us/style-guide/welcome/whats-new
7월 17일
OpenAI에 대한 회고 (calv.info)
https://news.hada.io/topic?id=22012
본문은 OpenAI에서 1년 정도 일한 엔지니어가 남긴 회고인데, 댓글 중에 기술 문서에 대한 언급이 있습니다.
> 이렇게 빠르게 성장한 회사임에도, OpenAI의 테크니컬 라이터 부족이 계속 놀라움, 문서가 개선될 수 있다고만 표현하는데, 실제로 Anthropic의 문서화 수준과 비교하면 OpenAI에는 동료 테크라이터를 찾기 힘듦, 좋은 개발자 도구를 만들려면 우수한 문서가 필수이며, 이를 전담하고 발전시키는 팀이 꼭 필요함
첫 번째 댓글을 남긴 분은 Fabrizio Ferri Benedetti(https://passo.uno/)입니다. OpenAI에서 일하는 건 아니고 테크니컬 라이팅 관련 컨설팅을 주로 하는 분인데, 아마도 본인 정도라면 OpenAI에서 일하는 테크니컬 라이터를 알고 있어야 하는데, 주변에서 OpenAI에서 일하고 있다는 사람이 없다 뭐 그런 의미 아닐까 싶네요.
> 경영진이 문서화의 가치를 못 느끼는 게 문제임, 예전에 DigitalOcean에선 업계 최고 수준의 기술 문서팀이 있었지만, 정리해고 때 가장 먼저 잘렸음, 비용으로만 보는 시선이 크다고 느낌
두 번째 댓글에 언급된 DigitalOcean 이야기는 2023년 2월 소식이었네요. 해커뉴스에 올라온 내용이구요. 팀 전체가 해고되었다는 이야기입니다.
> Yes, I was a technical writer on the content team. I am hearing that our entire team was laid off. It just isn't a big money-maker in these trying times. More of a cost center, I suspect.
It's too bad, as DO tutorials and content have been respected for so many years by developers and sysadmins. The end of an era.
https://news.ycombinator.com/item?id=34804603
7월 21일
오픈소스 기여 실전, 처음이면! 개발가이드 컨트리뷰션으로 쉽게 시작하세요!
https://youtu.be/HL8VIV9JHdU?si=8GVY2Jy801jP9Uaa
표준프레임워크 오픈커뮤니티에서 "2025 전자정부 표준프레임워크 컨트리뷰션" 행사를 9월까지 진행하고 있습니다.
코드, 아이디어, 가이드 문서 3가지 분야로 참여할 수 있는데, 가이드 문서에 기여하는 방법에 대한 안내 영상이 2개 올라와 있습니다. 정확하게는 1개는 안내이고, 1개는 팁 같은 성격입니다.
특히, 경력이 없는데 테크니컬 라이터로 뭔가 해보고 싶은 분들에게 추천할만한 활동이네요. 해외에는 오픈소스 쪽 문서화에 기여할 기회가 많지만 한국(한국어 사용자를 위한)에서는 기회가 많지 않거든요.
저도 아직 내용을 확인해보지 못해서. 시간이 되면 살펴보고 내용을 정리해보겠습니다. 일단 참고를 위해 링크 공유합니다.
개발가이드 컨트리뷰션 자동화 해보기! 개발가이드 자동화툴! ★Markdown Converter 함께 보아요! ★
https://youtu.be/hsSm1tVqF_k?si=BdQ8ll7US09kNcRA
7월 25일
2025 차세대반도체 컨소시엄 공대생을 위한 실전 테크니컬 라이팅 교육 프로그램
https://ngscc.kr/sub/sub04_01.php?boardid=notice&mode=view&idx=76
일반인이 신청할 수 있는 건 아니고 요건에 맞는 학생만 신청할 수 있는 프로그램입니다.
교육주제 정도 참고하시면 좋을 듯합니다.
독특하게도 2명의 강사가 모두 변리사입니다. 변리사는 기술과 법률을 아우르는 특허 관련 전문적 테크니컬 라이팅 능력을 보유하고 있으나, 산업 전반의 기술 문서 작성에 특화된 테크니컬 라이터와는 그 목적과 범위에서 차이가 있습니다. 변리사의 작문 전문성은 주로 기술적·법률적 문서 작성 및 특허 청구서 등에 집중되어 있고, 일반 사용자를 위한 기술 문서 작성과는 좀 거리가 있을 수 있습니다. 그럼에도 어느 정도 경험이 있으신 분들이니 이런 교육도 할 수 있는 것이겠죠.
"AI 시대 인터넷 검색은 끝났다? 하나만 아시네요"
https://v.daum.net/v/URDShyBW25
텍스트웨이 유승민 대표 인터뷰인데, 제품을 만들게 된 계기에 대해 테크니컬 라이터 시절 어려움을 언급하는 부분이 있습니다.
...테크니컬 라이터 시절 정보 관리하는 게 너무 힘들었습니다. 가이드에 써야 하는 각 기능의 특징을 일일이 노트에 수기로 기록했죠. 회사 보안 때문에 컴퓨터로 관리하는 데 한계가 있었거든요. 석사 논문을 쓸 때도 인용할 내용을 잔뜩 찾아두고도 안 쓴 게 너무 많았어요. 수소문해보니 저만 겪는 문제가 아니었습니다. 회사 내에서도 정보 교류가 잘 안돼, 이미 정리된 자료가 있는데도 굳이 밤새워 보고서를 작성하거나 관련 자료를 못 찾는 일이 비일비재했어요. 모은 정보를 디지털화해서 쉽게 찾을 수 있게끔 하면 정보를 효율적으로 잘 관리할 수 있겠다 생각했죠..
