의 테크니컬 라이팅 가이드라인

DigitalOcean은 서버 관리 및 소프트웨어 엔지니어링과 관련된 기술 문서 컬렉션을 계속해서 구축하게 되어 기쁩니다. DigitalOcean 기사가 일관된 품질과 스타일을 갖도록 하기 위해 다음 지침을 개발했습니다.

이 가이드에는 네 개의 섹션이 있습니다.

• 스타일, 기술 자습서 작성에 대한 높은 수준의 접근 방식
• 구조, 레이아웃 및 콘텐츠 설명
• Markdown 참조 가이드인 서식 지정
• 용어, 일반적인 용어 및 단어 사용에 대한 가이드

빨리 게시하려면 기사 작업을 시작하기 전에 전체 구조 섹션을 읽는 것이 좋습니다.

기사를 작성하는 동안 DigitalOcean 커뮤니티 자습서에 대한 제안서 및 개요 작성 방법을 참고 자료로 사용할 수 있습니다.

또한 기술 중심 권장 사항을 설명하는 기술 모범 사례 가이드도 있습니다.

문서의 시작점으로 사용할 수 있는 Markdown 형식의 문서 템플릿을 개발했습니다. 이 템플릿 중 하나를 사용하여 기사를 계획하고 개발하는 것이 좋습니다.

기사 스타일에 대해 알아 보려면 계속 읽으십시오.

스타일

DigitalOcean 기사의 스타일은 엔지니어와 개발자에게 양질의 학습 정보를 제공하기 위해 기사를 게시하는 목적을 반영합니다. 우리는 모든 DigitalOcean 튜토리얼이 다음과 같은지 확인하기 위해 노력합니다.

• 모든 경험 수준을 위한 포괄적이고 작성
• 기술적으로 상세하고 정확함
• 실용적이고 유용하며 독립적인
• 친절하지만 격식

이러한 원칙은 작성자가 사람들이 문제를 해결하고 개발자로 성장하는 데 도움이 되는 기사, 자습서 및 기타 학습 자료를 작성하도록 안내합니다.

모든 경험 수준을 위한 포괄적이고 작성됨

우리 기사는 독자의 배경 지식에 대한 가정 없이 가능한 한 명확하고 상세하게 작성되었습니다.

독자가 새로운 서버의 첫 번째 SSH 연결에서 최종 작업 설정까지 이동하는 데 필요한 모든 명령을 명시적으로 포함합니다. 또한 독자에게 튜토리얼을 이해하는 데 필요한 모든 설명과 배경 정보를 제공합니다. 목표는 독자가 코드와 명령을 복사하여 붙여넣는 것이 아니라 개념을 배우는 것입니다.

\simple\, \straightforward\, "easy\, "simply\, "명백하게\, "just\와 같은 단어는 독자의 지식을 가정하기 때문에 사용하지 않습니다. 저자는 이 단어를 사용하여 독자가 도전적인 주제를 통해 밀어붙이도록 격려하고 동기를 부여하지만 종종 반대 효과를 나타냅니다. \쉽다\는 말을 듣는 독자는 문제를 만났을 때 좌절할 수 있습니다. 대신 우리는 독자가 성공하는 데 필요한 설명을 제공함으로써 독자를 격려합니다.

기술적으로 상세하고 정확함

당사의 기사는 기술적으로 정확하며 업계 모범 사례를 따릅니다. 또한 코드와 명령보다 더 많은 세부 정보를 제공합니다. 우리는 큰 블록의 구성이나 프로그램 코드를 제공하지 않고 독자들에게 그것이 작동하고 안전하다는 것을 믿고 텍스트 편집기에 붙여넣도록 요청합니다. 독자가 기사를 이해하고 신뢰하는 데 필요한 모든 세부 정보를 제공합니다.

모든 명령에는 필요에 따라 옵션 및 플래그를 포함하여 자세한 설명이 있어야 합니다. 모든 코드 블록 뒤에는 그것이 무엇을 하고 왜 그렇게 작동하는지를 설명하는 산문적 설명이 뒤따라야 합니다. 독자에게 명령을 실행하거나 구성 파일을 수정하도록 요청할 때 먼저 그 기능이 무엇이며 독자에게 그러한 변경을 요청하는 이유를 설명하십시오. 이러한 세부 정보는 독자에게 기술을 향상시키는 데 필요한 정보를 제공합니다.

저자는 정확성을 보장하고 누락된 단계를 식별하기 위해 새로운 서버에 작성된 대로 정확하게 따라 작동하는지 확인하기 위해 튜토리얼을 테스트합니다. 또한 편집자는 검토 프로세스의 일부로 이러한 기사를 테스트하여 독자에게 훌륭한 학습 경험을 제공합니다.

실용적이고 유용하며 독립형

독자가 DigitalOcean 기사를 마치면 처음부터 끝까지 무언가를 설치, 구축 또는 설정한 것입니다. 우리는 실용적인 접근 방식을 강조합니다. 기사의 끝에서 독자는 사용 가능한 환경이나 구축할 예제를 가져야 합니다.

이것이 작가에게 의미하는 바는 기사가 주제를 철저히 다루어야 한다는 것입니다. 저자는 독자가 튜토리얼을 시작하기 전에 선행 조건으로 기존 DigitalOcean 기사에 링크하고 튜토리얼 본문에 추가 정보를 제공하기 위해 사용 가능한 DigitalOcean 기사에 링크해야 합니다. 저자는 기존 DigitalOcean 기사가 없고 짧은 요약으로 정보를 기사에 직접 추가할 수 없는 경우에만 독자를 외부로 보내 정보를 수집해야 합니다.

친절하지만 형식적인

우리의 튜토리얼은 친근하면서도 형식적인 어조를 목표로 합니다. 즉, 기사에 전문 용어, 밈, 과도한 속어, 이모티콘 또는 농담이 포함되지 않습니다. 우리는 전 세계 청중을 위해 글을 쓸 때 언어와 문화적 경계를 넘어 작동하는 어조를 목표로 합니다.

블로그 게시물과 달리 1인칭 단수를 사용하지 않습니다(예: "I think …”). 대신 2인칭 사용을 권장합니다(예: "You will configure …”). 독자와 그들이 성취할 것. 경우에 따라 1인칭 복수를 사용합니다(예: "우리는 ...을 조사할 것입니다.\).

우리는 결과에 초점을 맞춘 동기 부여 언어를 권장합니다. 예를 들어 "Apache 설치 방법을 배우게 됩니다.\ 대신 "이 자습서에서는 Apache를 설치합니다.\라고 입력하십시오. 이 접근 방식은 독자에게 동기를 부여하고 달성해야 하는 목표에 초점을 맞춥니다.

마지막으로, 튜토리얼의 언어는 다양한 인간 경험을 존중하고 커뮤니티 행동 강령을 따릅니다. 즉, 연령, 장애, 민족, 성 정체성 또는 표현, 경험 수준, 국적, 신경 다양성, 개인적 외모, 인종, 종교, 정치적 소속, 성적 오리엔테이션, 사회경제적 지위 또는 기술 선택.

구조

DigitalOcean 기사는 서론, 결론 및 독자가 시작하는 데 필요한 전제 조건을 포함하는 일관된 구조를 가지고 있습니다. 그러나 특정 구조는 기사 유형에 따라 다릅니다.

우리가 게시하는 대부분의 자습서는 절차적이며 독자가 작업을 단계별로 수행하는 과정을 안내합니다. 절차 문서의 구조는 다음과 같아야 합니다.

• 제목(레벨 1 제목)
• 소개(레벨 3 제목)
• 전제 조건(레벨 2 제목)
• 1단계 - 첫 번째 작업 수행(레벨 2 제목)
• 2단계 - 다음 작업 수행(2단계 제목)
• …
• n단계 - 마지막 작업 수행(레벨 2 제목)
• 결론(수준 2 제목)

개념 문서에는 제목, 소개 및 결론이 있지만 전제 조건 섹션이 없거나 \단계 규칙을 따르지 않을 수 있습니다.

• 제목(레벨 1 제목)
• 소개(레벨 3 제목)
• 전제 조건(선택 사항)(레벨 2 제목)
• 하위 주제 1(수준 2 제목)
• 하위 주제 2(레벨 2 제목)
• …
• 하위 주제 n(레벨 2 제목)
• 결론(수준 2 제목)

일부 기사는 매우 작은 특정 작업이나 솔루션에 더 초점을 맞추고 있으며 종종 제목, 짧은 소개 문장 및 끝에 결론이 있습니다. 해당 기사는 다음과 같은 구조를 갖습니다.

• 제목(레벨 1 제목)
• 소개 단락
• 전제 조건(선택 사항)(레벨 2 제목)
• 기사 본문
• 결론 단락

우리 기사 템플릿에는 Markdown에 이미 작성된 이 구조가 있으며, 이 템플릿을 자신의 기사에 대한 시작점으로 사용하는 것이 좋습니다.

제목

제목을 작성할 때 독자가 튜토리얼을 따라 무엇을 달성할지 신중하게 생각하십시오. 독자가 목표를 달성하기 위해 사용할 도구뿐만 아니라 튜토리얼의 목표를 제목에 포함시키십시오. 이상적으로 제목은 60자 미만이어야 합니다.

절차 자습서의 일반적인 제목은 다음 형식을 따릅니다. 에서 <소프트웨어>로 <작업 수행> 방법.

예를 들어 자습서가 Caddy 웹 서버 설치에 관한 것이라면 목표는 Nginx 서버를 보호하는 것일 수 있습니다.

목표를 포함하는 제목(예: "Ubuntu 22.04에서 Cloudflare 및 Nginx를 사용하여 웹사이트를 호스팅하는 방법\)은 일반적으로 목표를 포함하지 않는 제목(예: "Ubuntu 22.04에서 Cloudflare 및 Nginx를 사용하는 방법\)보다 독자에게 더 많은 정보를 제공합니다. ).

소개

모든 기사의 첫 번째 섹션은 일반적으로 1~3개의 단락 길이인 서론입니다. 서론의 목적은 독자에게 동기를 부여하고, 기대치를 설정하고, 독자가 기사에서 할 일을 요약하는 것입니다. 귀하의 서론은 다음 질문에 답해야 합니다.

• 이 튜토리얼은 무엇에 관한 것입니까? 관련된 소프트웨어는 무엇이며 각 구성요소는 어떤 역할을 합니까(간단히)?
• 독자가 이 주제를 배워야 하는 이유는 무엇입니까? 이 구성에서 이 특정 소프트웨어를 사용하면 어떤 이점이 있습니까? 독자가 이 튜토리얼을 따라야 하는 실질적인 이유는 무엇입니까?
• 이 튜토리얼에서 독자는 무엇을 하거나 만들까요? 서버를 설정한 다음 테스트하고 있습니까? 앱을 만들고 배포하고 있습니까? 독자에게 필요한 동기를 부여하고 주제에 대한 흥미를 유발하므로 구체적으로 작성하세요.
• 읽기를 완료하면 독자는 무엇을 성취하게 될까요? 그들은 어떤 새로운 기술을 갖게 될까요? 이전에는 할 수 없었던 일을 할 수 있게 될까요?

서론에서 이러한 질문에 답하면 튜토리얼의 내용을 서론에서 언급한 내용과 일치시키므로 명확하고 독자 중심적인 튜토리얼을 설계하는 데 도움이 됩니다. 좋은 서론은 학습자가 기사의 나머지 부분이 무엇에 관한 것인지 알 수 있게 해줍니다.

독자와 그들이 성취할 것에 초점을 맞추십시오. "우리는 방법을 배울 것입니다\와 같은 문구를 사용하는 대신 "당신이 구성할 것입니다\ 또는 "당신이 구축할 것입니다\와 같은 문구를 사용하세요. 이는 독자에게 동기를 부여하고 주제에 대해 흥미를 갖게 하는 데 큰 도움이 됩니다. 또한 기술보다는 독자가 해결하고 있는 문제에 계속 초점을 맞추세요. 예를 들어 튜토리얼이 React로 프로젝트를 구축하는 것이라면, React가 무엇인지 설명하는 것보다 프로젝트에 대한 소개에 집중할 수 있습니다.

전제 조건

DigitalOcean 기사의 전제 조건 섹션에는 매우 구체적인 형식과 목적이 있습니다.

목적은 독자가 현재 자습서를 따르기 전에 수행해야 하는 작업을 정확히 설명하는 것입니다. 형식은 독자가 체크리스트로 사용할 수 있는 목록입니다. 각 지점은 필수 콘텐츠를 다루는 기존 DigitalOcean 튜토리얼 또는 현재 DigitalOcean 튜토리얼이 없는 경우 공식 제품 문서에 연결되어야 합니다. 이를 통해 처음부터 시작하는 대신 작동하는 것으로 알려진 기존 콘텐츠에 의존할 수 있습니다.

우리의 시스템 및 DevOps 자습서는 독자를 바닐라 배포 이미지의 새로운 배포에서 작업 설정으로 안내하므로 서버에 대한 첫 번째 SSH 연결로 시작하거나 이를 수행하는 필수 자습서를 포함해야 합니다.

시스템 관리 및 DevOps 자습서에 대한 공통 전제 조건은 다음과 같습니다.

• 배포, 초기 서버 설정 및 추가 필수 옵션(예: 메모리 요구 사항, DO API 키, IPv6 또는 사설 네트워킹)을 포함하여 필요한 서버 수
• Apache, LAMP 스택 또는 데이터베이스와 같은 소프트웨어 설치 및 구성
• 필수 DNS 설정 또는 SSL 인증서.

당사의 소프트웨어 개발 자습서는 유사한 방식으로 작동하여 독자에게 개발 환경에 대한 전제 조건을 포함하여 사전에 필요한 모든 전제 조건을 제공합니다.

소프트웨어 개발 자습서의 일반적인 전제 조건은 다음과 같습니다.

• Git, Node.js, Python, Ruby 또는 Docker와 같은 로컬 소프트웨어가 필요합니다.
• GitHub, Facebook, Twitter 또는 독자에게 필요한 기타 서비스와 같은 추가 사용자 계정
• HTML 프로젝트를 설정하는 방법과 같이 독자가 프로젝트를 시작하는 데 도움이 되는 자습서
• DOM 이해와 같이 독자에게 도움이 될 수 있는 중요한 배경 정보를 제공하는 개념적 문서

예를 들어 Node.js 애플리케이션을 빌드 및 배포하고 Git을 사용하여 Ubuntu 서버에 배포하는 방법에 대한 자습서에는 다음과 같은 전제 조건이 있을 수 있습니다.

이 자습서를 완료하려면 다음이 필요합니다.

• 루트가 아닌 sudo 사용 사용자 및 방화벽을 포함하여 Ubuntu 22.04 초기 서버 설정 가이드에 따라 Ubuntu 22.04 서버 1개를 설정했습니다.
• 서버를 가리키도록 구성된 도메인 이름. 도메인 및 DNS 가이드에 따라 도메인을 DigitalOcean Droplets로 지정하는 방법을 배울 수 있습니다.
• 로컬 컴퓨터에 설치된 Git. 오픈 소스에 기여: Git 시작하기 자습서를 따라 컴퓨터에 Git을 설치하고 설정할 수 있습니다.
• Node.js 설치 방법 및 시스템용 로컬 개발 환경 생성 방법으로 설정할 수 있는 Node.js용 로컬 개발 환경

전제 조건을 읽으면 독자는 시작하기 전에 수행해야 할 작업을 정확히 알 수 있습니다. 놀라움은 없습니다.

자습서를 테스트할 때 모든 사람이 동일한 시작점을 사용하도록 작성된 필수 자습서를 모두 정확하게 따르십시오. 변수를 변경하거나 전제 조건 중 하나에서 선택적 단계를 완료하는 경우 이를 참고하십시오.

다음에 대한 좋은 전제 조건 예제를 검토할 수 있습니다.

• 이 Minio 자습서의 전제 조건에 있는 Ubuntu 20.04 서버, 소프트웨어 설치 및 DNS 레코드.\n
• 이 Nagios 및 Alerta 자습서의 전제 조건에서 소프트웨어 설치로 여러 서버를 처리합니다.\n
• Jest 및 React Testing Library로 React 앱을 테스트하는 방법을 읽고 React 기반 웹 개발 프로젝트.\n

전제 조건을 구체적으로 지정하십시오. 특정 항목에 대한 링크가 없는 "JavaScript에 대한 친숙함\과 같은 전제 조건은 독자에게 많은 컨텍스트를 제공하지 않습니다. 대신 독자가 알아야 하는 특정 개념을 나열하고 성공적으로 완료할 수 있도록 속도를 높이는 데 도움이 되는 리소스를 제공하세요. 예를 들어 "Javascript에 익숙함. 기술을 쌓으려면 JavaScript로 코딩하는 방법 시리즈를 확인하세요.”

단계

단계 섹션은 독자가 수행해야 하는 작업과 그 이유를 설명하는 자습서의 일부입니다. 단계에는 명령, 코드 목록 및 파일이 포함되어 있으며 수행할 작업뿐만 아니라 이러한 방식으로 수행하는 이유에 대한 설명도 제공합니다.

각 단계는 수준 2 제목으로 시작합니다.

절차 자습서는 각 단계 제목을 Step이라는 단어와 숫자로 시작하고 그 뒤에 em-대시가 옵니다. 단계 제목은 독자가 해당 단계에서 수행할 작업을 설명하고 다음과 같이 동명사(-ing 단어)를 사용합니다.

1단계 – 사용자 계정 만들기

제목 뒤에 독자가 각 단계에서 수행할 작업과 자습서의 전체 목표를 달성하는 데 수행하는 역할을 설명하는 소개 문장을 추가합니다. 독자에게 집중하십시오. "우리는 배울 것이다\ 또는 "내가 설명할 것이다\와 같은 문구 대신 "당신은 건설할 것이다\ 또는 "당신은 창조할 것이다\와 같은 문구를 사용하세요.

단계별 명령

판독기가 실행해야 하는 모든 명령은 자체 코드 블록의 자체 줄에 있어야 하며 각 명령 앞에는 명령이 수행하는 작업을 설명하는 설명이 있어야 합니다. 명령 다음에 인수가 수행하는 작업 및 판독기가 인수를 사용하는 이유와 같은 명령에 대한 추가 세부 정보를 제공합니다.

다음 명령을 실행하여 모든 숨겨진 파일을 포함하여 /home/sammy 디렉토리의 내용을 표시합니다.

ls -al /home/sammy

-a 스위치는 숨겨진 파일을 포함하여 모든 파일을 표시하고 -l 스위치는 타임스탬프 및 파일 크기를 포함한 긴 목록을 표시합니다.

다음 예와 같이 별도의 코드 블록을 사용하여 명령 및 프로그램의 출력을 표시해야 합니다.

hello.js 프로그램을 실행합니다.

node hello.js

프로그램의 출력이 화면에 인쇄됩니다.

Output
Hello world!
This is my first Node.js program!

출력 블록에는 레이블이 있으며 출력을 설명하는 일부 텍스트와 함께 명령과 구분됩니다. 출력에서 명령을 분리하면 명령이 끝나고 출력이 시작되는 위치가 독자에게 더 명확해집니다.

리더가 디렉토리 사이를 이동할 경우 이러한 이동에 필요한 명령을 제공해야 합니다.

파일 열기, 생성 및 보기

명령과 마찬가지로 항상 일반적인 목적을 설명하여 파일이나 스크립트를 소개한 다음 독자가 파일에서 수행할 모든 변경 사항을 설명합니다. 이러한 설명이 없으면 독자는 문제를 사용자 지정, 업데이트 또는 해결할 수 없습니다.

사용자에게 사용할 각 파일을 만들거나 열도록 명시적으로 지시합니다.

명령줄 사용자를 대상으로 하는 자습서에서는 자체 줄에서 명령을 사용하여 파일을 만들고 열도록 독자에게 지시합니다.

다음 명령을 사용하여 /etc/hginx/config 파일을 엽니다.

nano /etc/nginx/sites-available/default

Ubuntu 및 Debian 자습서에는 이미 설치된 nano 편집기를 사용합니다. CentOS 및 FreeBSD에 대한 자습서에서는 vi를 사용합니다. 모든 경우에 touch를 사용하여 새 빈 파일을 만들지 마십시오. 독자가 편집기로 직접 파일을 만들 수 있습니다.

프런트 엔드 개발 자습서와 같이 독자가 명령줄 인터페이스를 사용하지 않을 것으로 예상되는 자습서의 경우 파일을 여는 명령을 생략할 수 있습니다. 그러나 어떤 파일을 열어야 하는지 독자에게 명시적으로 알려야 합니다.

편집기에서 src/App.js 파일을 엽니다.

독자는 작업 중인 파일을 항상 알고 있어야 합니다.

코드 블록

우리는 모든 코드를 학습의 기회로 취급합니다. 독자에게 코드 작성을 요청하는 경우 명령과 동일한 접근 방식을 따르십시오. 수행하는 작업에 대한 높은 수준의 설명과 함께 코드 블록을 소개합니다. 그런 다음 코드를 표시한 다음 중요한 세부 정보를 호출합니다.

예를 들면 다음과 같습니다.

텍스트 편집기에서 hello.js 파일을 만듭니다.

nano hello.js

화면에 메시지를 출력하는 다음 코드를 파일에 추가합니다.

console.log("Hello world!");
console.log("this is my first Node.js program!")

console.log 함수는 문자열을 가져와 자체 줄에 화면에 출력합니다.

코드 블록에는 파일 이름을 명확하게 표시하는 레이블이 있습니다.

이 Docker Swarm 자습서는 로컬뿐만 아니라 여러 다른 서버에서 실행되는 명령을 구별하기 위해 사용자 지정 Markdown을 사용하는 방법에 대한 좋은 예입니다.

때때로 당신은 파일을 열고 독자에게 특정한 것을 변경하도록 요청할 것입니다. 이 작업을 수행할 때 파일의 관련 부분을 표시하고 강조 표시를 사용하여 변경해야 할 사항을 명확하게 합니다.

편집기에서 /etc/nginx/sites-available/default 파일을 엽니다.

nano /etc/nginx/sites-available/default

server_name 값을 도메인 이름으로 변경합니다.

server {
    listen 80 default_server;
    listen [::]:80 default_server ipv6only=on;

    root /usr/share/nginx/html;
    index index.html index.htm;

    server_name your_domain;
...

}

변경 내용과 필요한 이유를 설명하십시오.

DigitalOcean의 사용자 정의 Markdown 및 서식 지정 지침은 자습서의 지침을 가능한 한 쉽게 읽을 수 있도록 설계되었습니다.

전환

각 단계는 짧은 소개 문장과 독자가 성취한 것과 다음에 어디로 갈 것인지를 설명하는 마무리 전환 문장으로 구성되어야 합니다. 전환은 독자를 안내하고 지침, 명령 및 출력에 대한 중요한 컨텍스트를 제공합니다. 반복을 피하려면 단계 제목을 반복하지 않도록 이러한 문장에 사용되는 언어를 변경하십시오.

다음은 Rocky Linux 8에서 Let's Encrypt로 Nginx를 보호하는 방법에 대한 이 자습서의 1단계 끝에서 전환의 예입니다.

이제 Let’s Encrypt 클라이언트를 설치했지만 인증서를 받기 전에 필요한 모든 포트가 열려 있는지 확인해야 합니다. 이렇게 하려면 다음 단계에서 방화벽 설정을 업데이트합니다.

위의 예에서 저자는 독자가 달성한 것을 요약하고 다음 작업을 소개하며 두 단계가 어떻게 연결되는지 설명했습니다.

이러한 방식으로 각 단계의 프레임을 구성하면 독자가 학습하고 계속 진행하도록 동기를 부여할 수 있습니다.

결론

튜토리얼의 결론은 독자가 튜토리얼을 따라 수행한 내용을 요약해야 합니다. "우리는 방법을 배웠습니다.\와 같은 문구를 사용하는 대신 "당신이 구성했습니다.\ 또는 "당신이 구축했습니다.\와 같은 문구를 사용하세요.

결론은 또한 독자가 다음에 수행할 수 있는 작업을 설명해야 합니다. 여기에는 독자가 탐색할 수 있는 사용 사례 또는 기능에 대한 설명, 추가 설정 또는 구성이 있는 다른 DigitalOcean 자습서에 대한 링크, 외부 문서에 대한 링크가 포함될 수 있습니다.

몇 가지 좋은 예는 이 node-csv 튜토리얼의 결론입니다.

포맷팅

DigitalOcean 튜토리얼은 Markdown 마크업 언어로 형식화되어 있습니다. 커스텀 마크다운. 맞춤형 Markdown의 예는 아래 해당 섹션에 있습니다.

헤더

자습서의 각 섹션에는 해당 헤더가 있습니다. 제목은 H1 헤더여야 합니다. 소개는 H3 헤더여야 합니다. 전제 조건, 단계 및 결론에는 H2 헤더가 있어야 합니다. Markdown 문서 템플릿에서 이 형식을 검토할 수 있습니다.

절차 자습서의 경우 단계 헤더에는 단계 번호(숫자)와 전각 대시(—)가 있어야 합니다.

단계 헤더는 -ing 단어인 동명사도 사용해야 합니다. 단계 헤더의 예는 1단계 - Nginx 설치입니다.

H3 헤더는 드물게 사용하고 H4 헤더는 피하십시오. 하위 헤더를 사용해야 하는 경우 자습서의 해당 섹션 내에 해당 수준의 헤더가 두 개 이상 있는지 확인하세요. 또는 여러 단계를 수행하는 것이 좋습니다.

라인 레벨 포맷

다음과 같은 경우 굵은 텍스트를 사용해야 합니다.

• 보이는 GUI 텍스트
• wordpress-1 또는 sammy와 같은 호스트 이름 및 사용자 이름
• 용어 목록
• 새 서버나 사용자로 전환하는 것과 같이 명령에 대한 컨텍스트를 변경할 때 강조

이탤릭체는 기술 용어를 소개할 때만 사용해야 합니다. 예를 들어 Nginx 서버는 로드 밸런서가 됩니다.

인라인 코드 서식은 다음에 사용해야 합니다.

• unzip과 같은 명령 이름
• mysql-server와 같은 패키지 이름
• 선택적 명령
• ~/.ssh/authorized_keys와 같은 파일 이름 및 경로
• 예: http://your_domain
과 같은 URL
• :3000
과 같은 포트
• ENTER와 같이 모두 대문자여야 하는 키 누르기. 키를 동시에 눌러야 하는 경우 CTRL+C와 같은 더하기 기호(+)를 사용하십시오.

코드 블록

코드 블록은 다음 용도로 사용해야 합니다.

• 튜토리얼을 완료하기 위해 독자가 실행해야 하는 명령
• 파일 및 스크립트
• 터미널 출력
• 텍스트로 된 대화형 대화

줄임표(. . .)로 파일에서 발췌 및 생략을 표시합니다. 독자가 변경해야 하는 경우 강조 표시를 사용합니다.

server {
    listen 80 default_server;
    listen [::]:80 default_server ipv6only=on;

    root /usr/share/nginx/html;
    index index.html index.htm;

    server_name your_domain;
...

}

대부분의 파일을 기본 설정으로 남겨둘 수 있는 경우 일반적으로 변경해야 하는 섹션만 표시됩니다.

독자가 기존 코드에 줄을 추가하는 경우 강조 표시를 사용하여 새 줄이나 기타 변경 사항을 나타냅니다. 다음은 Go 모듈 사용 방법 자습서의 예입니다.

mymodule 디렉터리에서 main.go 파일을 열고 아래 강조 표시된 줄을 추가하여 PrintHello에 대한 호출을 추가합니다.

package main

import (
	"fmt"

	"mymodule/mypackage"
)

func main() {
	fmt.Println("Hello, Modules!")

	mypackage.PrintHello()
}

위의 예에서 독자가 추가할 항목이 모두 강조 표시되어 있습니다.

코드 블록 접두사

코드 블록에 명령 프롬프트($ 또는 #)를 포함하지 마십시오. 대신 루트가 아닌 사용자 명령, 루트 사용자 명령 및 사용자 지정 접두사에 각각 DigitalOcean의 사용자 지정 마크다운을 사용하십시오.

```command
sudo apt update
```

```super_user
adduser sammy
```

```custom_prefix(mysql>)
FLUSH PRIVILEGES;
```

앞의 예제가 렌더링되는 방식은 다음과 같습니다.

sudo apt update

adduser sammy

FLUSH PRIVILEGES;

이런 식으로 명령을 제시하면 독자가 실수로 프롬프트 문자를 선택할 수 없습니다.

코드 블록 레이블

DigitalOcean의 Markdown에는 레이블과 보조 레이블도 포함됩니다. 블록의 아무 곳에나 [label Label text] 또는 [secondary_label Secondary label text]가 있는 행을 추가하여 코드 블록에 레이블을 추가할 수 있습니다.

레이블을 사용하여 파일 내용이 포함된 코드 블록을 파일 이름으로 표시합니다. 예를 들어 app.js라는 파일이 있는 경우 [label app.js]를 사용하여 코드 블록에 레이블을 지정합니다.

```js
[label app.js]
console.log("Hello World!");
```

라벨은 코드 목록 위에 표시됩니다.

console.log("Hello World!");

보조 레이블을 사용하여 다음과 같이 화면에 인쇄된 터미널 또는 프로그램 출력을 표시합니다.

```
[secondary_label Output]
Hello World!
```

보조 레이블은 다음과 같습니다.

Output
Hello World!

레이블은 독자가 읽고 있는 내용과 그것이 더 큰 그림에 어떻게 부합하는지 이해하는 데 도움이 됩니다.

코드 블록 환경 색상

때로는 리더가 로컬 시스템 및 여러 서버와 같은 여러 컴퓨터에서 작동하도록 할 수 있습니다. 환경 디스플레이에 다른 색상을 사용하면 독자가 쉽게 따라갈 수 있습니다. DigitalOcean의 Markdown을 사용하면 블록의 아무 곳에나 [environment name]가 있는 줄을 추가하여 코드 블록의 배경색을 칠할 수 있습니다. name의 옵션은 local, second, third, fourth입니다. 및 다섯 번째.

예를 들어 자습서를 작성 중이고 서버 대신 로컬에서 실행해야 하는 명령을 표시하려는 경우 [environment local]을 사용할 수 있습니다.

ssh root@your_server_ip

다음은 다중 서버 설정에 유용한 비기본 서버 명령 예입니다.

[environment second]를 사용하면 다음과 같이 렌더링됩니다.

echo "Secondary server"

[environment third]를 사용하면 다음과 같이 렌더링됩니다.

echo "Third server"

[environment four]를 사용하면 다음과 같이 렌더링됩니다.

echo "Fourth server"

그리고 [environment five]는 다음과 같이 렌더링됩니다.

echo "Fifth server

다중 서버 또는 다중 환경 자습서에서 이러한 색상을 사용하십시오. 필요한 경우 로컬 환경의 이 샘플 출력 블록과 같이 환경 레이블과 출력 레이블을 스택하여 다른 환경 내의 파일을 나타낼 수 있습니다.

Output
Hello World!

중첩 레이블은 판독기가 적절한 터미널 세션에서 명령을 실행하는 데 필요한 모든 정보를 갖도록 합니다.

참고 및 경고

DigitalOcean Markdown 파서는 사용자 지정 메모 및 경고 코드 블록을 사용하여 매우 중요한 텍스트를 표시할 수 있습니다.

다음은 메모 및 경고의 마크다운 예시입니다(이미지입니다).

렌더링 결과는 다음과 같습니다.

참고: 이것은 참고 사항입니다.

경고: 이것은 경고입니다.

DigitalOcean 관련 정보

[정보] 콜아웃은 DigitalOcean 특정 기능을 논의할 때 유용합니다.

이 기능은 DigitalOcean의 Droplets에만 적용됩니다.

변수

예제 URL, 버전 번호 또는 구성 파일의 수정된 줄과 같이 판독기가 변경해야 하는 모든 항목을 강조 표시합니다. 사용자 지정 <^> Markdown으로 단어나 줄을 둘러싸서 이 작업을 수행할 수 있습니다.

다음은 Ubuntu 22.04를 사용한 초기 서버 설정의 예입니다.

이 예에서는 sammy라는 새 사용자를 생성하지만 이를 원하는 사용자 이름으로 바꿔야 합니다.

adduser sammy

참고: 한 쌍의 기호로 여러 줄을 강조 표시할 수 없으므로 각 줄을 개별적으로 강조 표시해야 합니다. 경우에 따라 셔뱅(#) 또는 백틱과 같은 기호가 줄의 강조 표시 기능을 손상시킬 수 있으며 같은 줄에 두 개의 강조 표시된 섹션이 필요할 수 있습니다.

일반적으로 인라인 코드 서식도 사용하는 컨텍스트에서 변수를 참조하는 경우 두 스타일을 모두 사용해야 합니다. \위에서 빨간색으로 강조 표시됨\ 대신 \이전 코드 블록에서 강조 표시됨\과 같은 언어를 사용하여 자습서에 최대한 액세스할 수 있는지 확인하세요.

강조 표시 색상이 변경될 수 있으므로 "노란색으로 강조 표시됨\과 같은 표현은 피하세요.

이미지 및 기타 자산

이미지는 요점을 빠르게 설명하거나 단계에서 추가 설명을 제공할 수 있습니다. GUI 스크린샷, 대화형 대화 및 서버 설정 다이어그램에 이미지를 사용하십시오. 코드, 구성 파일, 출력 또는 문서에 복사하여 붙여넣을 수 있는 항목의 스크린샷에 이미지를 사용하지 마세요.

자습서에 이미지를 포함할 때 다음 지침을 따르십시오.

• 스크린 리더를 사용하는 독자가 이미지가 아닌 대체 텍스트에 의존할 수 있도록 설명 대체 텍스트를 포함합니다.
• 기사의 맥락 내에서 이미지를 맥락화하는 간단한 캡션을 포함합니다(캡션은 일반적으로 대체 텍스트보다 짧습니다).
• .png 파일 형식을 사용합니다.
• imgur에서 이미지를 호스팅합니다.
• 가능한 한 높이가 짧은 이미지를 만듭니다.

튜토리얼용 다이어그램 모형을 만들면 DigitalOcean 스타일의 다이어그램이 생성됩니다. 또한 발행 시점에 모든 이미지를 DigitalOcean 서버에 업로드할 것입니다.

다음은 자습서에 이미지를 포함하는 Markdown 예제입니다.

![Descriptive alt text for screen readers](http://imgur.com/your_image_url “Brief caption here”)

이 Matomo 튜토리얼의 이미지에서 강력한 설명 대체 텍스트의 예를 검토할 수 있습니다.

경우에 따라 너무 길어서 자습서의 본문에 표시할 수 없는 구성 파일에 독자가 액세스할 수 있기를 원할 수 있습니다. DigitalOcean은 자산 서버에서 이 파일을 호스팅합니다. 표준 링크 서식을 사용하여 파일에 연결할 수 있습니다.

술어

기술 문서 및 자습서는 많은 용어를 사용하며 일부 용어 및 단어 사용을 표준화했습니다.

사용자, 호스트 이름 및 도메인

기본 예시 사용자 이름은 sammy입니다. 도움이 되는 경우 webdav-kai 또는 nsd와 같이 설명적인 것을 선택할 수도 있습니다.

기본 호스트 이름은 your_server이지만 django\\_replica\\_1와 같이 다중 서버 설정에서 좀 더 설명적인 이름을 선택할 수 있습니다.

기본 도메인은 your_domain입니다. 다중 서버 설정의 경우 primary-1.your_domain 또는 replica-1.your_domain과 같은 것을 선택할 수 있습니다. example.com은 문서에 유효한 도메인이지만 자습서에서 your_domain을 사용하면 독자가 예제에서 도메인을 변경해야 함을 분명히 알 수 있습니다.

다음과 같이 구성 파일, 코드 및 출력 블록에서 사용할 때 강조 표시를 사용하십시오.

ip: your_server_ip
domain: primary-1.your_domain

이것은 독자들에게 그들이 변경해야 할 것이 있음을 분명히 합니다.

IP 주소 및 URL

인라인 코드 형식 및 변수 강조 표시가 있는 your_server_ip는 IP 주소를 표시하는 기본 방법입니다. primary_private_ip 및 replica_private_ip와 같은 이름으로 여러 IP 주소를 표시할 수 있습니다. 보다 현실적인 IP 주소를 설명해야 하는 경우 RFC-5737에 따라 문서용으로 예약된 두 블록 중 하나의 주소를 사용하십시오. 특히 공용 주소의 경우 203.0.113.0/24를 권장하고 개인 주소의 경우 198.51.100.0/24를 권장합니다.

독자가 맞춤설정해야 하는 변수가 포함된 예시 URL은 변수가 강조표시된 코드 형식을 사용해야 합니다. https://your_domain:3000/simple/ 또는 http와 같이 기본적으로 your_domain을 사용합니다. ://your_server_ip/. 그러나 라이브 링크는 추가 서식 없이 표준 Markdown 링크 스타일을 사용해야 합니다.

소프트웨어

공식 웹사이트의 소프트웨어 이름을 대문자로 사용하십시오. 제품 웹 사이트의 대소문자 표기가 일치하지 않는 경우 단일 기사 내에서 일관성을 유지하십시오.

소프트웨어를 처음 언급할 때 소프트웨어의 홈 페이지로 연결됩니다.

다중 서버 설정

기술적 명확성을 위해 다중 서버 설정에 대한 프로젝트 용어를 사용하십시오. 용어는 프로젝트에서 나온 것임을 분명히 하십시오. 예: "Django 프로젝트는 원본 서버를 기본 서버로, 보조 서버를 복제본으로 참조합니다. MySQL 프로젝트는 원본 서버를 마스터로, 보조 서버를 슬레이브로 참조합니다.”

다중 서버 아키텍처를 보다 추상적으로 논의할 때는 기본 및 복제 또는 관리자 및 작업자라는 용어를 사용하십시오.

기술 모범 사례

당사의 기술 모범 사례 가이드 가이드에는 독자에게 도움이 되는 일관되고 고품질의 자습서를 만드는 데 도움이 되는 추가 지침이 포함되어 있습니다.

이 링크를 따라 DigitalOcean 작가가 되십시오.