본문 바로가기

테크니컬 라이팅

구글 엔지니어는 기술 문서를 어떻게 쓸까?

반응형

올해 3월에 나온 책(Software Engineering at Google)에 담긴 내용 중 기술 문서와 관련된 챕터를 정리해보았습니다. 25개 챕터 중 하나의 챕터로 Documentation을 다루고 있고, 다른 챕터와 연결되어 있습니다. 이렇게 연결된 구조는 기술 문서가 엔지니어링 프로세스와 별개의 작업이나 역할로 보는 것이 아니라 통합된 프로세스 안에 포함되어 있다는 것을 보여줍니다 (물론 저자는 여전히 부족하다고 이야기합니다).

www.oreilly.com/library/view/software-engineering-at/9781492082781/

 

Software Engineering at Google

Today, software engineers need to know not only how to program effectively but also how to develop proper engineering practices to make their codebase sustainable and healthy. This book emphasizes … - Selection from Software Engineering at Google [Book]

www.oreilly.com

각 챕터별로 "Edited by"가 표시되어 있습니다. 메인 저자인 Tom Manshreck와 함께 Lisa Carey, Riona MacNamara가 참여했구요. 3명 다 구글 테크니컬 라이터입니다. 이 책에 참여한 저자들이 10명 이상인데, 일관성 있는 전달을 위해 편집 단계에서 많은 공을 들인 모양입니다. Riona MacNamara 같은 경우는 링크드인에 본인 소개를 "Documentation advocate and evangelist"라고 써놓았습니다. 구글 검색에서 같은 소개문을 사용하는 사례가 없는 걸로 보아 공식적인 직함은 아닌듯 합니다. 하여간 리오나 본인 소개문 중 아래와 같은 글이 있습니다.

Documentation is as fundamental to the discipline of software engineering as testing.
www.linkedin.com/in/rionam/

이 짧은 문장에 담긴 이야기가 Documentation 챕터에서 하고 싶은 이야기이기도 합니다.

 

Overall, the state of engineering documentation in the late 2010s is similar to the state of software testing in the late 1980s.
Everyone recognizes that more effort needs to be made to improve it, but there is not yet organizational recognition of its critical benefits.

테스트 역시 엔지니어링 프로세스에 쉽게 녹아들지 못했습니다. 조직에 따라 다르겠지만, 지금도 더 많은 노력이 필요한 분야이기도 합니다. 이 책에서도 11장부터 14장까지는 테스트와 관련된 내용을 다루고 있습니다. 문서는 1980년대 테스팅 상황과 비슷하다고 하니(구글은 좀 괜찮아지고 있다는 이야기를 뒤에 이어갑니다. 80년대 이야기는 전반적인 시장의 상황) 아직 여전히 갈 길이 멀다는 거죠.

 

But because documentation’s benefits are all necessarily downstream, they generally don’t reap immediate benefits to the author. 
Unlike testing, which (as we’ve seen) quickly provides benefits to a programmer, documentation generally requires more effort upfront and doesn’t provide clear benefits to an author until later.

이런 이유 중 하나는 문서의 이득을 즉각적으로 얻을 수 없다는 겁니다. 테스트는 바로 결과를 확인하고 코드의 개선을 이끌어 낼 수 있지만 문서는 그렇지가 않죠. 미래의 독자를 통해 보상을 받는다고 하지만 엔지니어에게 당장 다가오는 이야기는 아닙니다. 이런 면이 개발 조직에 문서를 프로세스로 받아들이는데 장벽이 된다고 합니다.

 

Documentation is often so tightly coupled to code that it should, as much as possible, be treated as code.
That is, your documentation should:

그래서 구글에서 선택한 방법은 문서를 코드처럼 다루도록 한 것입니다. 일정한 규칙을 가지고 코드와 같은 수준으로 버전을 관리하고 명확한 소유자를 지정하고 코드 변경 시 문서 작성이 하나의 프로세스로 흘러가도록 하는거죠.

 

When Google was much smaller and leaner, it had few technical writers. The easiest way to share information was through our own internal wiki (GooWiki). At first, this seemed like a reasonable approach; all engineers shared a single documentation set and could update it as needed.

개발 문서 작성을 위해 위키가 적당한지에 대한 논의는 구글 뿐 아니라 다른 곳에서도 발견할 수 있습니다.

softwareengineering.stackexchange.com/questions/72787/are-wikis-really-appropriate-to-store-documents-for-software-development

stackoverflow.com/questions/99419/what-is-the-best-way-to-store-software-documentation

규모가 작을 때는 위키 시스템으로도 관리할 수 있지만, 규모가 커지면 소유자가 명확하지 않거나 업데이트되지 않는 문서 또는 중복된 정보 등의 문제가 발생한다고 합니다. 때문에 구글이 성장하면서 문서의 품질은 점점 나빠졌다고 합니다. 여기서 이야기하는 문서는 외부에 공개되는 문서보다는 내부에서 사용하는 기술 문서에 해당합니다. 예를 들어 새로운 팀원이 합류했을때 개발 환경을 어떻게 설정해야 하는지 확인할 수 있는 명확한 문서가 없고 있더라도 잘 동작하지 않았다는거죠.

 

Google eventually introduced its own framework for embedding documentation within code: g3doc. With that framework, documentation improved further, as documents existed side by side with the source code within the engineer’s development environment.

그래서 문서를 코드의 영역 안으로 끌고 들어왔고 g3doc과 같은 프레임워크를 사용해 품질을 높였다고 합니다.

g3doc은 텐서플로우 저장소에서 찾아볼 수 있는데, 그 외 다른 저장소에서는 잘 보이지가 않습니다. 아직 진행중이라 그런 것 같기도 하고~

 

Because they are a limited resource, technical writers should generally focus on tasks that software engineers don’t need to do as part of their normal duties. 
Usually, this involves writing documents that cross API boundaries.

마지막에는 테크니컬 라이터의 역할에 대해서도 언급합니다. 모든 개발조직이 만드는 문서를 테크니컬 라이터에게 맡기려는 움직임도 있지만, 제한된 자원의 문제와 현실적인 어려움이 있다고 합니다. 그래서 테크니컬 라이터는 개별 엔지니어가 다루기 모호한 포괄적인 영역을 담당하고 나머지 코드와 연결된 부분은 엔지니어가 기술 문서를 담당합니다.

 

* 지난 9월에 WTD 샌프란시스코에서 올린 Tom Manshreck의 강연과 Q&A 세션 영상이 있습니다. 책이 나오기까지의 작업과 관련 주제를 다루고 있는 듯 합니다.

youtu.be/ePD9DwgmGOE

* 한국어 번역은 한빛미디어에서 진행하고 있다고 합니다. 올해 안에는 나오지 않을까 싶네요.

728x90