기술 문서 작성을 위한 샘플 코드

🐾들어가며

Docs for Developers 의 chapter5 샘플 코드 통합하기를 읽고 정리했습니다.

이번 챕터에서는 샘플 코드의 유형 별로 작성하는 원칙에 대해 다루며, 유용한 샘플 코드를 설계하는 것을 목표로 하고 있습니다.

✨본격적으로

✅샘플 코드 유형

- 실행 가능형: 필요에 따라 일부 수정하여 사용할 수 있는 바로 실행이 가능한 형태
- 설명형: 뭔가 배우거나 자신의 코드와 비교하고자 사용하는 출력 결과나 코드 블록 ex) API 문서

이번에는 vue js  공식문서를 예시로 들었습니다! 아래는 순서대로 실행 가능형 코드와 설명형 코드입니다.

✅좋은 샘플 코드의 원칙

독자는 샘플 코드가 그냥 잘 작동하기를 기대하비다. 독자는 문서를 훑어보고, 샘플 코드를 찾고, 샘플 코드에서 나타나는 개념을 파악하고, 가능하면 코드를 복사하여 붙여넣을 수 있기를 원합니다. 그들은 또한 이 코드가 항상 최신 상태이고 실제 운영 환경에서 작동하기를 원합니다.

설명형 샘플 코드
- 설명이 제공됨: 필요한 경우 맥락과 설명을 제공하고자 텍스트 본문 또는 코드 주석에 설명이 함께 나온다.
- 간결함: 독자가 필요로 하는 만큼의 정보를 제공한다.
- 명확함: 샘플 코드가 작성된 언어에 대해 독자가 기대하는 규칙을 따른다.

실행 가능형 코드
- 설명, 간결함, 명확함을 포함
- 사용 가능함(&확장 가능함): 독자가 샘플 코드를 사용하는 방법과 자신만의 데이터를 입력해야 하는 위치가 명확하다.
- 신뢰할 수 있음: 복사 & 붙여넣기가 가능하고, 잘 돌아가며, 독자가 기대하는 기능만 수행한다.

> 간결하게 만든다는 것은 더 짧게 만드는 것이 아니다!! 사용자가 작업을 완료하는 데 필요한 필수 정보만 전달하는 것.

vue js 공식문서에서도 샘플 코드에 주석을 사용해 코드의 설명을 제공하고 있습니다.

✅샘플 코드 설계하기

1. 프로그래밍 언어 선택하기: 사용자가 개발에 사용하는 언어로 제공하자.
2. 복잡도 강조하기: 다양한 복잡도를 가진 샘플 코드를 제공하자. 단, 복잡한 고급 예제로 인해 문서에 어려움이 없게 할 것.
3. 코드 적절히 표시하기: 포매팅과 스타일을 선택하자.

-> 샘플 코드를 위한 도구
- 테스트
- 샌드박스
- 자동 생성

vue js 에서 제공하는 예제들입니다. 바로 실행해서 볼 수 있게 샌드박스 형식의 샘플 코드를 보여주고 있습니다.

✔️결론

이번 챕터는 코드와 관련된 내용으로 특히 개발자가 읽기에 다양한 공식문서들이 생각나는, 좋은 주제인 듯 합니다. 특히 어떤 변수를 바꿔야 하는 지가 헷갈리는 샘플 코드를 만났을 때는 적잖히 당황했던 경험들이 생각났습니다. 내용이 짧고 당연한 소리를 하는 것 같지만, 당연하지 않은 샘플 코드들이 존재하기에 더 신경써서 문서를 작성해야 겠다고 생각했습니다.