Documentation - 프로그램 문서 작성

hyperskill - Documentation 영어 원문

Introduction - 소개

---

당신이 방금 프로그램을 마무리했으며, 유저와 동료 프로그래머에게 공유 할 준비가 되었다고 상상 해 봅시다.

프로그램을 작업하는 동안, 당신은 아마 거의 대부분 코드를 작성하는 데 집중했을 겁니다.

그러므로, 기계는 임무를 완수하기 위해 필요한 것을 이해할 것이며,

마지막으로 프로그램은 올바르게 실행 될 겁니다.

하지만, 사람들이 어떻게 당신의 프로그램이 동작하는 방식을 알며,

어떤 것이 가능하고, 어떤 것이 불가능하며, 해결해야 하는 문제들을 알 수 있을까요?

가장 중요한 것으로,

당신은 조금의 시간이 지난 후에 이러한 모든 질문들에 답변할 수 있나요?

확실하게 당신과 다른 사람들이 프로그램을 시간과 장소에 상관없이 사용할 수 있는 하나의 방식은,

코드에 문서를 작성하는 겁니다.

코드에 문서를 작성하는 방식들을 알아 내 봅시다.

Strategies for documenting code - 코드 문서 작성하는 전략

---

Documentation (문서작성) 은 소스 코드를 동반하는 작성된 혹은 묘사된 정보의 종류이며,

코드가 어떻게 동작하는지 혹은 어떻게 사용하는지 설명하는 것에 초점을 맞춥니다.

당신의 코드에 문서를 작성하는 몇 가지 방식들을 봅시다.

• 특정 부분의 코드가 무엇을 위한 것인지 이해하는데 돕기 위해 설명적인 주석을 작성하세요.
• 어떻게 작동하는지 이미지, 블록 스키마, 다이어그램, 다른 그래픽적인 예시 데이터를 제공하여 보여주세요.
• 코드 활용에 대한 모든 중요한 정보를 담은 README 파일을 작성하세요.
• 추가적인 정보를 담은 PDF, HTML 파일, 가이드, 핸드북 등을 제공하세요.
• 당신의 문서를 관리하기 위한 wiki(위키) 를 생성하세요.
• 릴리즈 노트, 변화기록을 작성하세요.

이에 대한 더 많은 정보를 얻기 위해서, 초보자를 위한 가이드 를 참조하세요.

README

---

README 는 주로 평문 텍스트 파일인데,

프로젝트에서 이 프로그램의 무엇이 동작하며 왜 동작하는지에 대한 설명을 제공합니다.

README 파일에 대한 제한된 정책은 없습니다.

하지만, 당신은 몇 가지 공통적으로 사용되는 섹션에 대해서 참조해야 합니다 :

• Name : 이름
• Description : 설명
• Installation : 설치
• Usage : 사용법
• FAQ : 자주 물어보는 질문들
• Support : 지원
• Contributing : 배포
• Contact information : 연락처
• License : 라이센스
• Acknowledgment : 사례

Wiki - 위키 문서

---

위키는 기본적으로 여러 명의 유저에 의해 작성되는 웹사이트입니다.

따라서, 이는 특별히 팀 프로젝트에 대해 편리합니다.

전체 위키를 작성하는 것은 쉽지 않습니다.

따라서, 당신은 몇 가지 도구들이 필요하며,

이를 어떻게 하면 될지에 대한 추천이 필요합니다.

이런 유형의 작업에 가장 유명하게 사용되는 소프트웨어 중 하나는

MediaWiki 입니다.

이는 무료이며, 공개된 문서 작성 플랫폼으로서,

개인화 된 방식으로 당신의 프로젝트에 대한 정보를 정리하는 데 도움을 줍니다.

분명히, 이러한 포맷의 문서 작성은 README 파일보다,

디자인이나, 기능성 면의 측면에서 당신에게 더 많은 자유를 줍니다.

따라서, 당신은 완성적이고 클릭 가능한 테이블의 컨텐츠를 생서하거나,

미디어 파일들을 추가하거나, 알맞은 들여쓰기로 코드 스니펫을 넣을 수 있습니다.

Release notes/changelogs - 노트, 변화기록 릴리즈

---

릴리즈 노트와 변경기록 은 특정한 유형의 문서 작성인데,

이는 알리기 위해 사용되거나, 업데이트를 추적하는 데 사용됩니다.

따라서, 이는 version control (버전 컨트롤)에 대해 특별히 유용합니다.

프로젝트에서 무언가가 변경되었을 때,

당신은 유저들과 동료들에게 이러한 새로운 버전이 이전과 무엇이 다른지 알려주기 위해,

Release Note 를 작성합니다.

예를 들면, 무엇이 새로운지, 무엇이 고쳐졌는지, 무엇이 지양되는지(deprecated), 등등

릴리즈 노트를 작성함으로서 당신은 프로그램이 잘못되거나, 부서진 순간을 항상 알 수 있습니다.

심지어 만약 당신이 아직 이러한 파일들을 퍼블리싱을 계획하지 않았더라도,

당신 스스로를 위해 이러한 릴리즈 노트들을 유지하는 것은 좋은 연습입니다.

Auto-generated documentation - 자동 생성 문서 작성

---

또한, 서로 다른 핵심적인 기능성을 가진 외부 도구들이 있습니다.

이러한 외부 도구들은 당신의 코드를 위해 문서를 생성하는 도움을 주는 데 초점이 맞춰져 있습니다.

대부분의 경우에 대해서 중요하게 참고해야 하는 것이 있는데,

이러한 도구들은 당신을 위해서 자동적으로 문서를 작성하지 않습니다.

이러한 도구들의 작업은 대부분은 첫 번째로 소스 코드 내부에 임베딩 된 주석을 기초로 하기 때문에,

이러한 도구들은 간단하게 더 구조화되고 읽기 쉬운 형식으로 이미 작성된 것을 변환하는 겁니다.

예를 들어, Doxygen 많은 언어들을 지원하며,

소스 코드로부터 HTML 파일들을 생성 할 수 있습니다.

Sphinx 는 원래 Python 문서 작성을 위해 개발되었으며, 테이블을 만들거나, 문서 트리들을 정의하는 데 준비되었습니다.

Dr. Explain 은 프론트엔드 개발자들을 위한 도구이며,

이는 어플리케이션의 유저 인터페이스를 분석하고, 빠르게 문서를 생성하며, 유저 친화적인 방식입니다.

이 목록은 완전하지 않으므로, 당신 스스로 무언가를 찾아 낼 수 있습니다.

Pros and cons - 장점과 단점

---

하나의 방식, 혹은 또 다른 방식으로 당신의 코드에 문서를 작성하는 것은,

당신이 좋은 프로그래머가 되기 위한 당신의 여정에 문서 작성 스킬을 마스터하는 것은 꽤 중요합니다.

따라서, 무엇이 중요하고, 그곳에 어떤 함정이 있는지 요약하겠습니다 :

Pros - 장점

• 당신의 기억을 되살리는 데 도움을 줍니다.
• 코드를 통해 당신을 가이드합니다.
• 코드가 어떻게 작동하는지, 어떻게 사용하는지 설명 해 줍니다.
• 버그를 고치는 데 도움을 줍니다.
• 버전 컨트롤에 대해 허용 해 줍니다.

Cons - 단점

• 많은 시간이 듭니다.
• 구조적이고, 깔끔하게 만들기 위해 연습이 필요합니다.
• 쉽게 기한이 지나므로, 매 시간 업데이트가 필요합니다.
• 영어로 문서를 작성하는 평범한 연습은 당신에게 외국어가 될 수 있습니다.
• 지속적인 피드백은 정말로 프로그램을 좋게 만드는 데 필요합니다.

Summary - 요약

---

이번 주제에서는, 우리는 소프트웨어 문서 작성에 대한 것을 배웠으며,

문서 작성의 유형, 어떻게 작성하는지, 그리고 장점과 단점에 대해서 배웠습니다.

이제 우리는 이러한 중요한 정보가 서로 다른 유형의 소프트웨어를 사용하는 데 도와주며,

이것이 어떻게 작동하는지 이해하고 설명하는 데 도움을 준다는 것을 알고 있습니다.

또한 우리는 도움이 되는 몇 가지 문서 생성기에 대한 몇 가지를 살펴보았습니다.

모두 합쳐서, 이것들로부터 모두는 혜택을 받을 수 있는 아주 강력한 도구입니다.

하지만, 이를 능속하게 사용하기 위한 노력에는 시간이 듭니다.

words to remember

---

regardless : ~에 관계없이, 부주의한, 비용에 구애되지 않고

regard : 관심, 관련, 고려, 주시, 알다, 보다, 생각하다

accompanies : 동행하다, 따르게 하다, 동반하다, ~을 수반하다

inform : 알리다, ~에게 고하다, 통지하다, ~을 채우다

pitfalls : 함정

proficiently : 능숙하게