Docs for Developers 리뷰 :: 마이구미

이 글은 "Docs for Developers - 기술 문서 작성 완벽 가이드" 라는 책을 리뷰한다.
본인은 평범한 프론트엔드 개발자이다. 개인적인 생각과 해석이 들어가 있을 수 있다.
책 링크 - https://m.yes24.com/Goods/Detail/118266847

 

 

이 책은 제목 그대로 "기술 문서" 에 관련된 글이다.

대부분의 개발자는 문서화의 중요성과 필요성은 느끼고 있을 것이다.

하지만 문서를 작성하는 것도 힘들고, 문서화를 하더라도 최신화하면서 유지보수하는 것은 더더욱 어려운 과제이다.

본인은 문서화를 추구하는 입장이지만, 동료들에게까지 전파하여 체계적으로 관리하는 것은 성공하지 못하고 있다.

그래서 이 책은 새로운 무언가를 배울 수 있지 않을까? 해서 구매를 시도해보았다.

 

알다시피 문서의 종류는 다양하다.

문서는 제품의 성격이나 팀 상황 등에 따라, 필요한 문서들이 결정된다.

이 책은 전반적인 문서를 설명하고는 있으나, 기본적으로 API 를 제공하는 서비스를 기반으로 작성되었다.

 

정말 많은 내용들이 있지만, 개인적으로 좋았던 몇가지만 기록용으로 남겨두려고 한다.

 

---

 

사용자 이해를 검증할 때는 사용자의 니즈에 중점을 두며, 이는 사용자의 욕구와는 다릅니다.

 

어딘가를 가야한다면, 누구나 스포츠카를 원할 수 있다. 

하지만 운전할 줄 모른다면, 버스표를 제공하는 편이 더 낫다. 스포츠카를 원하지만 버스표가 필요하다.

관련 문장의 의도를 알듯말듯... 더 좋은 예시와 실무에서 활용할 수 있을 것 같은데... 조금 더 생각해봐야겠다.

 

질문의 종류는 크게 3가지로 분류할 수 있다.

• 구체적인 질문
• 열린 질문
• 닫힌 질문

 

구체적인 질문은 가능한 답변의 범위를 적절히 제한하는데 도움이 됩니다.

열린 질문은 인터뷰 대상자가 답을 생각해 보게 하며, 이야기나 더 긴 설명으로 답하게 해 줍니다.

닫힌 질문은 답을 제한하며 일반적으로 예 또는 아니오로 답하게 합니다.

 

 

마찰 로그는 사용자가 하는 것처럼 소프트웨어를 사용해보고 자신의 경험을 적은 기록입니다.
마찰 로그로 문서화하여 사용자와 공감해야 합니다.

 

마찰 로그라는 용어가 좋은 것 같다.

잘 활용한다면, 이를 기반으로 사용성 개선이나 추후 절차 가이드 작성 등에 용이하게 사용할 수 있을 것으로 보인다.

 

용어집, 문제 해결 문서

 

수많은 종류의 문서가 있음 README, 시작하기, 개념, 절차, How-to, 릴리스 … 등이 있는데 그 중에서 "용어집", "문제 해결 문서" 가 조금 더 생각해보게 되었다.

실무에서는 비즈니스 도메인 용어가 굉장히 많다.

이러한 용어들은 그대로 코드 작성으로 이어진다.

네이밍을 이해하기 위해서는 용어에 대한 의미를 계속 찾을 수 밖에 없는데 조금 더 개발자를 위한 용어집을 만들어 놓는 것도 좋을 것 같다는 생각이 들었다.

 

또한, 다른 라이브러리를 사용할때 내부 상황에 따라, 공식적인 이슈나 버그는 아니지만, 이러한 것들을 위해 우회하는 방식과 같은 것들이 존재할 수 있다.

이러한 내용들이 정리된 "문제 해결 문서" 명칭을 가진 문서가 있으면  좋을 것 같다.

 

문서가 오래되는 문제를 피하는 한 가지 방법은 랜더링된 페이지에서 콘텐츠의 마지막 수정 날짜를 표시하는 것이다.

 

구글에서는 내부용 문서 상단에 최신성 알림을 위한 메타데이터를 추가할 수 있는 기능이 있다고한다.

예를 들어, 6개월 후 알림을 통해 해당 문서를 다시 검토하게 함으로써, 방치되지 않도록 도움을 줄 수 있는 좋은 방안으로 보인다.

 

문서를 유지 관리하려면 코드 작성과 문서 작성의 방향을 맞춰야합니다.

 

문서 유지 관리를 하는 방식으로 릴리스 프로세스에 문서 릴리스도 포함시키는 방식과 이슈가 생성되면, 설계 문서, 담당자, 단위 테스트, 문서화 필요 여부 등 필수 항목 체크하는 프로세스을 설명하고 있다.

가장 기본적으로 시도할 수 있는 방안이지만... 여러 이유로 쉽지 않은 것 같다.

 

F 패턴, Z 패턴

 

사용자가 콘텐츠를 읽는 패턴을 나타내는 용어라고한다.

관련 패턴에 대해 별도로 읽어보고 숙지하면 좋은 내용으로 보여진다.

 

픽사의 플러싱(Plusing) 규칙

 

 

플러싱 규칙은 "건설적인 제안을 더하는 경우에만 아이디어를 비판하세요." 라는 의미이다.

코드 리뷰에서 많이 언급될 수 있는데, 추후 상황에 따라 사용할 수 있는 용어로 보인다.

 

 

지식의 저주(curse of knowledge) - 다른 사람도 자신과 같은 지식을 갖고 있다.

 

개발자는 정말 많이 듣는 말이지 않을까? 이것을 표현하는 용어가 있다는 것을 처음 알았다.