위키를 이용한 기술문서 작성에서 배포까지
위키에서의 기술문서 작성: 기술 내용에 대한 How & Why 설명
Andrew Lui
이것은 위키를 이용한 기술문서 작성에 대한 Atlassian의 기술문서 작성팀의 포스트입니다.
이 글에서는 왜 위키가 기술문서에 대해 좋은 솔루션인지를 설명할 것입니다. 내용은 위키에서 어떻게 기술문서를 작성하고 게시하며, 문서의 구조 및 관리를 수행할 지를 알려줍니다.
위키는 이미 매우 오래전에 나온 것이지만 실제 저도 Atlassian에서 일하기 전에는 위키를 이용한 문서에 대해 고려해 보지 않았었습니다.
아마도 여러분도 마찬가지일 것이라고 생각됩니다.
자 이제 저와 함께 wiki bus
"위키는 재미있지만, 중요한 문서를 위한 것은 아니다."
위키는 기본적으로 다른 많은 사용자에 의해 컨텐츠가 쉽게 추가되고 편집되며 제거될 수 있는 웹사이트입니다.
이것은 여러분의 팀이 협력(협업)하는데 매우 도움을 주지만, 위키를 이용해 고객에서 여러 다양한 아이디어를 보여주려고 하지는 않을 것입니다.
저도 그렇게 생각했었습니다.
진실은, 위키가 문서에 대한 전반적인 것들을 지원하는 것과 같이 CMS 도구로의 지원도 할 수 있다는 것입니다.
위키는 문서 버전관리, 컨텐츠와 문서구조 재사용과 릴리스 관리, 원본 일원화(Single Sourcing)와 게시 그리고 많은 것을 수행합니다.
이제 이러한 것들에 대해 다음에 자세히 설명히 설명해 나갈 것입니다. 우선은 문서를 위한 위키 사용에 대해 제가 발견한 몇 가지 장점을 알려드리겠습니다.
1) 당신에게 도움을 줍니다. (기술 문서 작성자)
문서를 게시하는데 여러단계의 과정을 거치는 기존의 문서작성 툴을 이용해 왔다면, 위키에서 문서를 작성하는 것은 일종의 혁명이 될 수 있습니다.
실시간으로 공개되는 문서에서 실수를 수정하고 싶다면?
문서를 오픈하고 편집하고 저장합니다. 그만큼 간단합니다.
편집 방식 자체는 기존의 여러 HTML 혹은 XML 에디터를 사용하는 것보다 훨씬 편리할 수 있습니다.
많은 기업용 위키, (Confluence
이것은 태그하나를 빠뜨려 문서가 깨지는 것보다 훨씬 편리하게 업무 문서를 작성할 수 있도록 도와줍니다.
위키는 단지 문서작성뿐 아니라 게시 과정 또한 더욱 쉽게 할 수 있도록 합니다.
기술문서를 작성하기 위해 정보를 모우는 것은 때로는 제품 매니저, 개발자, 본인 사이의 여러 협력을 필요로 합니다.
리뷰를 위한 초안을 게시하는 것은 때로는 다른 사용자들의 많은 문서 댓글이나 혹은 초안의 업데이트를 통한 풍부한 피드백을 가져올 수 있습니다.
그리고 필요한 경우 패드백을 선택하거나 혹은 변경사항을 다시 원상태로 되돌릴 수도 있습니다.
2) 여러분의 고객에게 도움을 줍니다.
대부분의 위키는 시간이 부족한 고객들이 원하는 정보를 빠르게 찾을 수 있도록 전통적인 문서 툴을 가지고 있습니다. 즉, 강력한 검색엔진, 태그(레이블), 브레드크럼(문서위치링크), 탐색트리, 등등 입니다.
위키는 이러한 기능을 확장하여 고객들에게 더욱 풍부한 컨텐츠를 제공합니다.
개념에 대한 설명보다 데모가 더 쉽습니다? 페이지에 비디오를 추가해 보십시요.
복잡한 절차를 기술해야 하나요? 위키 페이지에 절차에 대한 다이어그램을 넣어보십시요.
애드온과 플러그인은 이러한 것과 같은 많은 기능들을 추가하는데 많은 일반적인 위키에서 사용될 수 있습니다.
만약 여러분의 문서를 서로 다른 형식으로 제공하는 것이 걱정스럽다면, 그러실 필요가 없습니다.
많은 위키들이 여러분의 문서들을 여러 다른 형식으로 바꾸어 저장할 수 있도록 하는 옵션을 제공합니다.
우리의 경우는 문서를 PDF, HTML 그리고 XML로 저장할 수 있습니다.
각각의 바뀐 저장 형식에도 서로 다른 스타일을 적용할 수도 있어 받는 사람을 위해 문서를 커스터마이즈 하는 것도 가능합니다.
위키에서 관리되는 문서는 고객 지원을 개선하는데에도 사용될 수 있습니다.
우리 지원부서는 때로 새로운 문서를 업데이트 혹은 추가하여, 고객이 최신의 문서를 확인 할 수 있도록 하고 있습니다.
위키는 또한 고객을 위한 또 다른 중요한 피드백 채널을 제공할 수도 있습니다.
페이지에 추가된 댓글은 제품이나 문서의 문제점을 알려주기도 하는 것입니다.
3) 여러분의 회사에게 도움을 줍니다.
고객이 여러분의 위키문서에 성난 댓글을 추가하는 것에 대해 신경이 쓰이시나요?
스패머가 스팸댓글을 달거나 할 것 같은가요?
여기 여러분이 생각해 볼 필요가 있는 다른면이 있습니다:
위키를 통해 다른 고객의 질문에 또 다른 고객이 답변을 하고, 외부 개발자가 샘플코드를 추가해 문서를 풍부하게 해 주고, 파트너가 새로운 문서를 자발적으로 작성하는 것들 입니다.
잘 관리되는 문서 위키는 고객 커뮤너티 자체를 활성화 시킬 수 있는 것입니다.
좋은 회사의 위키는 단계적인 문서접근권한, CAPTCHA, 스팸필터와 같은 툴을 제공하여 여러분의 커뮤너티가 여러분의 문서와 함께 안전하도록 해 줍니다.
많은 기관들이 이미 자신들의 문서를 위키로 관리하고 있습니다 – 여기 문서 위키 목록
어떤 위키는 다른 위키에 비해 더 비싼 금액에 더 많은 기능을 제공합니다.
예를들면, 단계적인 문서접근권한은 위키에서 기업문서를 관리하는데 보통 필수기능입니다.
이것은 오픈소스 위키에서는 쉽게 찾을 수 없는 기능입니다.
그러나, 위키 솔루션들의 가격 경쟁력에 매우 놀라실 것입니다.
만약 여러분의 기술문서 작성자가 위에 기술된 장점들을 이용할 수 있다면, 여러분의 전체 문서 프로세스를 단순화 할 수 있을 것입니다.
그리고 여러분의 회사는 결국 문서관리를 위한 비용을 매우 적게 사용할 수 있게 될 것입니다.
이것은 분명 검토해 볼 가치가 있는 것입니다.
위키에서 기술문서 작성: 초안에서부터 문서 게시까지
Giles Gaskell
이번에는 위키를 사용하여 문서를 작성하고 게시하는 방법에 대해 이야기 할 것입니다.
구조화된 컨텐츠를 지원하는 위키!
많은 사람들이 여전히 위키를 정형화되지 않은 페이지들의 집합으로 페이지에서 관련 문서 링크를 클릭하거나, 인덱스를 이용하거나 혹은 내장된 검색 엔진을 통해 검색된 결과를 이용해 원하는 페이지를 찾는 것으로 생각합니다.
모든 위키들이 그런 것은 아닙니다!
좋은 위키는 여러분의 페이지들을 '상위'와 '하위' 페이지의 계층구조로 구성할 수 있도록 해 줍니다.
이것은 파트, 챕터, 서브챕터, 섹션, 서브섹션등으로 구성되는 정보 매뉴얼이나 책을 쓸 때 원하는 형태의 컨텐츠를 생성할 수 있도록 도와줍니다.
Confluence
우리는 Confluence의 공간을 각각의 제품에 대해 버전별/에디션별 문서들을 관리하는데 사용합니다.
Confluence는 또한 공간 사이에 페이지들을 연결하여 컨텐츠를 재사용 할 수 있도록 도와줍니다.
저는 또한 여러분의 문서화의 좋은예로 Confluence Documentation Theme
여러분은 이 테마를 Confluence 사이트의 어떤 공간에도 적용할 수 있습니다.
이것은 웹브라우저의 왼쪽에 컨텐트 테이블 구조를 보여주고 사용자가 페이지들을 탐색할 수 있게 도와주면서 오른쪽에 바로 페이지의 내용을 보여주는 커스터마이즈 가능한 '온라인 도움말' 인터페이스를 제공합니다.
또한 왼쪽 컬럼에는 현재의 공간내의 페이지 트리로 검색을 제한하는 검색박스를 추가할 수도 있습니다.
Documentation Theme은 여러분의 문서화를 구조화하여 읽는이가 원하는 것을 더욱 쉽고 빠르게 확인할 수 있도록 도와 줍니다.
왜 위키가 협력적 문서화에 최적인가?
위키는 페이지 내용에 대해 초안을 작성하고 이것을 특정 그룹의 사람들에게 전체 게시 전에 리뷰하도록 할 수 있습니다.
또한 페이지에 보기와 편집 권한
예들들어, 여러분의 리뷰어에게 간단한 수정은 직접 문서를 편집하거나 큰 변경이 필요한 경우는 댓글을 올리도록 요청할 수 있습니다.
Confluence에서는 누가 페이지를 편집할 수 있고 누가 페이지에 댓글을 올릴 수 있는지를 제어
이것은 여러분이 문서의 직접적인 수정벗이 댓글을 통해 여러 그룹의 사람에게 피드백을 받을 수 있도록 해 줍니다.
페이지를 저장할 때는, Confluence가 페이지의 변경사항을 '페이지 히스토리'에 저장하여 기록합니다.
페이지에 변경사항이 원하는 내용이 아니거나 필요없게 되었다면, 적절한 이전의 문서 버전을 찾아 복원(롤백)할 수 있습니다.
또한 변경사항이 확실하지 않다면 히스토리에서 2개의 버전을 비교한 후 결정할 수도 있습니다.
리뷰 프로세스를 통해 협업문서를 잘 만들기 위해 다음과 같은 것들을 할 수 있습니다:
- 공간에서 수정된 특정 페이지나 컨텐츠가 있을 때 변경사항에 대해 통보 수령 (메일 혹은(과) RSS 피드 통해),
- 위키 사이트에서 다른 사용자의 활동사항을 팔로우하여 위키내에서 특정 사용자가 수정 혹은 추가한 문서를 추적
- 현재 작업하는 내용에 대해 다른 사용자가 알 수 있도록 나의 작업상태 공지(업데이트)
- 읽는 사람이 페이지 댓글을 통해 문서작성에 참여한다는 느낌을 부여 (혹은 원하는 문서를 업데이트하도록 하여)
책이나 매뉴얼처럼 내용을 구조화 하는 기능과 초안생성, 개정, 게시를 쉽게하는 여러 협업 기능을 이용하면 위키는 협업 문서화에 최적인 툴이 될 수 있는 것입니다.
어떻게 위키에서 컨텐츠를 쓰고, 변경하고 게시할 것인가?
새로운 위키 사이트 혹은 공간에 문서를 작성하려고 하였다면, 일반적으로 페이지의 '루트(root)'에서 시작하여 하위페이지를 추가하면서 여러분의 문서를 구성할 것입니다.
그러나, 더 일반적인 시나리오는 기존의 문서내용을 새로운 버전/에디션에 대해 갱신하는 것입니다.
기존의 컨텐츠 업데이트
Atlassian에서는, 모든 제품의 문서
우리는 현재의 '라이브' 제품 버전 공간에서 업데이트 되는 내용에 대한 초안을 생성하여 기존 제품의 새로운 버전 문서를 생성합니다.
Confluence는 Copy Space plugin
만약 이러한 공간들을 숨겨진 복사본으로 만들어 업데이트 한다면, 이러한 여러 동료들의 피드백을 받을 수 없을 것입니다.
그러면, 라이브 위키 공간에서 어떻게 문서를 업데이트 할까요? 2가지의 업데이트 방법이 있습니다.
---- 완전한 새로운 페이지와 개정이 필요한 기존의 페이지 문서입니다.
새로운 페이지에 대해서는, 새로운 페이지를 추가하여 적절한 보기/쓰기 권한을 부여한 후 내용을 추가하기 시작합니다.
개정이 필요한 페이지에 대해서는, 해당 페이지를 확인하고 이 페이지의 복사본을 생성합니다.
그리고 대상 페이지의 '하위' 복사본이 만들어지면 이것은 원본과 완전히 동일합니다. 그리고 우리는 필요한 보기와 편집 권한을 부여한 후에 내용을 수정하기 시작합니다.
여러분의 업데이트를 게시하기
초안 페이지(보기 접근권한과 함께)을 업데이트 한 후에는, 이것을 게시할 필요가 있습니다.
새로운 페이지에 대해서는, 매우 간단합니다. – 페이지의 보기 접근권한을 없애면 페이지가 게시(공개) 됩니다.
수정 페이지에 대해서는, 약간 복잡합니다.
일반적으로 하위 페이지에서 수정된 내용을 복사한 후, 상위 페이지로 붙여넣기 하여 이것을 덮어서 저장합니다.
하위 페이지는 더 이상 필요하지 않으므로 삭제합니다.
그러나, 만약 수정대상 페이지의 복사본을 만든 후에 누군가가 원래의 페이지를 수정하였다면 어떨까요?
그러면, 만약 다른 사람이 수정한 내용이 여러분이 수정한 내용이 관련된 부분이면, 수정된 내용을 게시 하기 전에 다른사람의 수정 내용을 합칠 필요가 있습니다.
이런 경우를 확인하기 위해 원본의 페이지에 업데이트를 하기 전에 해당 페이지가 수정되었는지 여부를 날짜로 확인하거나 혹은 변경사항 통보를 통해 확인합니다.
다음 단계는?
이제 위키를 이용하여 협력적으로 문서를 작성, 게시하는 방법을 알아보았습니다.
다음은, Sally Hawse가 어떻게 위키내에서 문서를 구조화하고 재사용하여시간을 절약하고 컨텐츠의 일관성을 최대화하는지에 대해 다음 포스트에 알려드릴 것입니다.
주) 골드피처
본 내용에 대해서는 이미 Confluence를 알고 계신 분들 보다는 위키를 단순이 위키피디어 수준으로만 생각하던 분들에게 도움이 될 것으로 생각됩니다.
조직내의 문서화는 아무리 강조해도 지나치지 않다는 것은 두말할 나위가 없으며 이것을 더욱 생산적으로 관리 유지하기 위한 대안 중에 하나가 기업용 위키 솔루션인 것입니다.
물론, 기업시장에서도 마이크로 소프트웨어의 오피스 제품의 위력은 매우 크기 때문에 국내의 대부분의 업무 문서가 워드, 엑셀, 파워포인트로 작성되는 현실에 비추어 보면 Confluence의 Office 문서 연동 기능
하지만, Confluence가 아닌 다른 위키라고 해도 기존의 문서 관리 시스템과의 조화로운 사용은 결국 조직의 문서화 경비를 절감시켜줄 것입니다.
이러한 이유로 국내에서도 MS Office 문서기반 문서화(Sharepoint 포함)와 위키를 같이 적절히 혼용하는 사례가 늘어나는 것이며, 어느 한쪽의 툴이 무조건 더 좋다기 보다는 장단점을 잘 파악하여 적절히 사용하는 것이 더욱 중요한 것임을 반증하는 것입니다.
그리고 이러한 위키를 사용하는데 있어 가장 중요한 것은 항상 사용자들(조직원들)이 서로 협력하려는 마음이라는 것을 항상 기억해야 할 것입니다.
댓글