외부 참여자를 위한 작성 스타일 지침 guidelines
이 페이지에서는 Experience League에서 콘텐츠를 만들거나 기존 콘텐츠를 업데이트하는 외부 작성자를 위한 에디토리얼 가이드라인을 제공합니다. 시작하기 전에 다음을 확인하십시오.
스타일 지침 style-guidelines
설명서를 작성할 때는 다음 사항을 기억하십시오.
- 간결하게 작성 - 단어를 낭비하지 마십시오. 문장을 짧고 간결하게 유지합니다. 문서에 초점을 맞춥니다. 참고 사항의 수를 최소로 유지합니다.
- 대상자 및 목적에 집중 - 작성을 시작하기 전에 고객이 누구이며 어떤 작업을 완수하려고 하는지를 명확히 파악하십시오. 해당 고객이 해당 작업을 수행하도록 돕는 문서를 작성하십시오.
- 사용 예 - 개념을 설명하는 예를 제공합니다.
- 내용 구성 - 섹션을 만들어 지침을 더 관리하기 쉬운 단계 그룹으로 분할합니다. 스크린샷으로 더 명확해진다면 스크린샷을 사용합니다.
기술 문서 작성의 모범 사례 writing-tips
특히 소프트웨어 설명서를 위한 기술 문서 작성은 전문 산업입니다. 아무리 많은 작품을 쓴 소설가라도 기술 문서 작성을 하려고 하면 당혹스러워합니다. 자료가 복잡하거나 기술적이어서가 아니라 복잡한 기술 정보를 간단하게 만드는 것이 쉽지 않기 때문입니다. 성공하려면 콘텐츠가 구조적으로 일관되고, 훑어볼 수 있고, 재사용 가능해야 하며 구조 및 구문 오류 없이 게시 파이프라인을 통해 흘러야 합니다.
다음 섹션에서는 신규 작성자가 주의해야 하는 일반적인 문제에 대해 설명합니다.
텍스트로 구분되지 않은 머리글 (이중 머리글) double-headings
구분하는 텍스트가 없는 두 개의 머리글이 있는 경우, 누락된 텍스트를 추가하십시오(두 번째 주제 머리글을 소개하기 위한 목적). 또는 머리글 중 하나를 제거할 수 있습니다. 두 번째는 아마도 불필요할 것입니다.
예를 들어 개요 는 여기서 아무 용도가 없습니다.
-
또한 두 번째 머리글이 개요 인 경우에는 불필요할 수 있습니다. H1과 첫 번째 단락은 문서의 주제에 대한 개념적 개요 역할을 합니다.
-
마찬가지로 SEO 용도로 개요 및 소개 와 같은 독립형 머리글은 그 자체로는 유용하지 않습니다. 소개하려는 제품이나 기능을 언급하십시오. (예: 폴아웃 보고서의 개요)
일관성 없는 상호 참조 머리글 maps
상호 참조 목록(또는 지도)에 대해서는 추가 정보 머리글을 사용하십시오. 예:
상호 참조 목록에 대한 지침
- 상호 참조에 글머리 기호 목록 사용
- 안내서의 정식 이름이나 페이지 이름에는 기울임체 사용 (링크 텍스트를 사용하지 않는 경우)
- 머리글에 구두점 사용 금지
- 머리글에 숫자 사용 피하기
TOC 항목, 경로 및 페이지 이름 불일치 toc
TOC(목차) 파일은 수동으로 관리하기 때문에 이러한 불일치는 흔한 실수입니다. 목차 항목이 페이지 이름(H1)과 일치하는지 확인하십시오. 또한 경로와 거의 일치하는지 확인하십시오.
TOC 및 목록에 대한 지침
- 목차 항목의 길이를 줄여야 할 수도 있지만, 목차 항목은 페이지 이름 및 경로와 명확하게 관련되어야 합니다.
- 경로는 제목 메타데이터에서 가져오므로 둘이 서로 다를 수 있습니다(SEO 용도상).
기울임체 대신 따옴표 quotes
단어나 구 주위에 따옴표를 추가하기가 쉽습니다. 하지만 따옴표는 말을 인용하기 위한 것이며 제품 설명서에는 거의 사용되지 않습니다.
따옴표에 대한 지침
- 일반적으로 기울임체가 따옴표보다 적합합니다(오류 메시지, 고유어 또는 외국어 등의 경우).
- 인터페이스 요소의 경우 굵게 표시하고 UICONTROL을 사용하십시오.
절차 steps
절차 작성(작업 콘텐츠 유형)은 타고나는 재능이 아닙니다. 읽기 쉽고 명확한 절차를 구축하려면 연습이 필요합니다.
단계에 대한 지침
- 절차는 일련의 단계입니다. 단계는 간단하고 번호가 매겨진 한 문장 명령입니다.
- 각 단계는 동사로 시작하거나 '~하려면' 형태로 작성하십시오(독자에게 목표를 안내하기 위함, 예: _로그인 상태를 유지하려면 로그인 상태 유지 _를 활성화하십시오). 단계에 전체 절차 내 특정 목표가 있는 경우 동작 전에 목표를 언급하십시오.
- 단계에 대한 정보(단계 정보 라는 콘텐츠 유형이 있는 경우 단계 뒤에(단계로 들여쓰기) 또는 에셋(스크린샷, 비디오 또는 인터페이스 설명 목록) 뒤에 추가하십시오.
- 단계에 두 가지 작업이 있는 경우(예: 이것을 선택한 다음 저것을 선택하십시오) 하나의 짧은 문장으로 작성하십시오.
- 작업을 약 7~10단계로 제한하십시오. 한 작업에서 10개가 넘는 단계를 만드는 경우 두 작업으로 나누어야 할 수 있습니다. 이 부분에서는 본인이 생각하기에 최선의 판단을 내리십시오.
- 제품 설명서에서 머리글을 단계로 사용하지 마십시오. (튜토리얼의 경우 아래와 같이 예외)
- 다중 페이지 튜토리얼의 경우 머리글이 단계로 허용될 수 있습니다. 하지만 번호는 매기지 마십시오. 대신 1단계:, 2단계: 등으로 작성하십시오.
예시 절차
다음은 이상적으로 구성된 Adobe 로그인 절차입니다.
Adobe에 로그인하려면 다음과 같이 하십시오.
Adobe.com에서 Experience Cloud 를 선택합니다.- 로그인 을 선택합니다.
- 개인 계정 을 선택합니다.
- 로그인 상태를 유지하려면 로그인 상태 유지 를 선택합니다.
- 이름과 암호를 입력합니다.
- 로그인 을 선택합니다.
병렬 목록 lists
목록에 병렬 구조를 사용하면 쉽게 읽고 훑어볼 수 있습니다. 목록에는 TOC(목차), 글머리 기호(순서가 지정되지 않은) 목록 또는 번호가 매겨진 목록이 포함됩니다.
병렬 항목이 있는 TOC의 예:
앞의 TOC는 다음과 같은 이유로 좋은 예입니다.
- 개념적 상위 항목이 명사 또는 명사구임
- 절차(작업)가 능동 동사임(동명사가 아님)
- 모든 항목의 각 단어 첫 문자에 대문자 사용
제목 및 설명 메타데이터 metadata
제목 및 설명 메타데이터는 SEO, 콘텐츠 검색 및 Experience League의 콘텐츠 품질 점수에 중요합니다.
다음은 제목 및 설명의 예입니다.
개념 문서에 대한 설명
- Adobe Analytics의 세그먼트에 대해 알아봅니다. 작업 영역에서 세분화 패널을 구성하는 데 대한 도움말을 봅니다.
- Adobe Analytics의 페이지 조회수 보고서에서 세그먼트를 사용하는 데 대한 도움말을 확인합니다.
절차/작업 문서에 대한 설명
- Adobe Analytics에서 세그먼트를 만드는 방법을 알아봅니다.
- Adobe Analytics에서 세그먼트를 만듭니다. 만든 세그먼트를 기반으로 보고서를 선택, 구성 및 실행하는 방법에 대해 알아봅니다.
사용하는 것은 문서의 크기와 범위에 따라 다릅니다.
개념 문서의 제목
- 페이지 조회수 보고서의 세그먼트
절차/작업 문서의 제목
- 페이지 조회수 보고서에 대한 세그먼트 만들기
(파이프 및 제품 이름은 제목에 자동으로 추가됩니다.)
명확성(및 Acrolinx 점수)을 개선하는 방법 tips
다음은 콘텐츠 디자인, 명확성 및 가독성을 개선하는 간단한 방법입니다. 이는 ExL에서 Acrolinx 스타일 점수와 CQI 점수를 개선하는 데도 도움이 됩니다.
약함: Campaign v8은 6월에 릴리스됩니다.
강력함: Campaign v8 릴리스 시기는 6월입니다.
현재 시제는 항상 고객이 읽기 쉽습니다.
매우, 굉장히, 대단히…
부사는 강력하고 정확한 동사, 절 및 형용사를 사용할 경우 중요한 의미를 덧붙이지 않는 부가 단어입니다.
예:
약함: 특성 생성 및 관리
강력함: 특성 만들기 및 관리
- '~하기 위해서는' 이라는 표현을 피하십시오(의미를 더하지 않음). 간단히 '~하려면' 이라고 하면 됩니다.
- 활용이라는 표현을 사용하지 마십시오. 더 기술적으로 들릴지 모르지만 그렇지 않습니다. 활용 은 특히 목적을 위해 의도된 것은 아니지만 도움이 되는 것을 잘 이용하는 것을 의미합니다.
- 세미콜론 피하기: 대신 마침표를 사용하고 새 문장을 시작하십시오. 세미콜론은 불필요한 복잡성을 가져옵니다.
- 콜론: 콜론을 사용하여 목록을 소개하십시오. 문장 내에서 콜론을 너무 자주 사용하지 마십시오. 문장에서 콜론 뒤 첫 단어의 첫 문자는 대문자로 표기하십시오.
- 옥스퍼드 쉼표(목록에서 쉼표 3개를 사용하는 방식)를 사용하십시오.
- 문장 길이를 39단어 미만으로 유지하십시오.
- 탐색: 이동 또는 탐색 이라는 표현을 사용하십시오.
- 경로를 표시하는 것이 중요한 정보가 아닌 경우 원시 URL 텍스트를 사용하지 마십시오(사용자에게 친숙한 링크 텍스트 사용).
클릭 은 특정 디바이스에 국한된 단어로서(접근성 문제 있음), 점점 사용하지 않는 추세입니다. 이 표현을 변경하는 데 대한 제안 사항은 다음과 같습니다.
- 탐색: 파일 > 인쇄로 이동합니다.
- 클릭: 파일 > 인쇄를 선택합니다 또는 확인을 선택합니다.
다양한 상황에서 최상의 단어 선택에 대한 자세한 아이디어는 UI와의 상호 작용 설명을 참조하십시오.
몇 가지 추가 모범 사례 및 리소스:
- 훑어보기가 가능한 콘텐츠: 독자가 필요한 것을 빠르게 찾거나, 필요한 위치에 있지 않을 때 빠르게 인지할 수 있도록 도와줍니다. 훑어보기를 용이하게 하기 위해 작성한다면 도움이 될 수 있습니다.
- 숫자: 본문에서 0에서 9까지의 정수는 단어로 쓰고 10 이상은 숫자를 사용하십시오. 숫자를 참조하십시오.
- 말하는 어조로 작성하고, 친근함을 담고, 요점에 빨리 도달하십시오.
자세한 내용은 Microsoft® 스타일 안내서의 주요 작성 팁 10가지를 참조하십시오.
대체 텍스트 alt-text
에셋(이미지)에 의미 있는 대체 텍스트를 추가하십시오. 다음과 일치하는 대체 텍스트를 고려하십시오.
- 고객이 달성할 수 있는 목표 (작업 또는 개념 이름)
- 표시 중인 기능 또는 페이지
- 표시되는 아이콘 이름
Google는 SEO 결과에서 대체 텍스트를 고려합니다.
현지화 - DNL 및 UICONTROL localization
제품이 현지화되었는지 또는 ExL이 사용하는 언어에 대해 걱정할 필요는 없습니다. 하지만 적절한 경우 다음 두 가지(필수) Markdown 태그를 적용하면 현지화 품질을 개선하는 데 도움이 됩니다.
-
DNLDNL은 현지화하지 않음(do not localize) 을 의미합니다. 상표가 등록된 Adobe 제품 이름에만 사용하며 이러한 이름은 모두 영어로 유지되어야 합니다.
구문 예:
Adobe Campaign또는WorkfrontDNL은 파일 이름이나 URL에는 해당되지 않습니다.
-
UICONTROLUICONTROL은 인터페이스 제어(예: UI의 옵션, 필드, 탭, 페이지, 옵션 그룹 또는 기능 이름)를 나타냅니다.
구문 예:
Select **Project**, then select **Save**.
제품 이름에 Adobe 사용 product-names
기업 정체성을 위해 일반적으로 안내서 수준에서 제품의 첫 번째 참조에 Adobe 를 포함합니다. 공간 고려 사항에 따라 머리글에서 Adobe를 뺄 수는 있지만 본문 사본의 첫 번째 참조에는 전체 이름이 포함되어야 합니다. Adobe Audition 및 Adobe Premiere Pro 와 같은 특정 제품은 첫 번째 또는 가장 중요한 참조에 Adobe를 사용해야 합니다. 이 경우 Adobe가 법적 상표 이름의 일부이기 때문입니다.
첫 단락 firstparas
첫 단락에서는 주제를 정의하고, 독자가 문서를 읽음으로써 무엇을 확인하게 되는지 설명해야 합니다.
샘플 첫 번째 단락(개념):
대상자는 방문자의 컬렉션입니다(방문자 ID 목록). Adobe의 대상자 서비스는 방문자 데이터를 대상자 세분화로 변환하는 작업을 관리합니다. 이와 같이 대상자를 만들고 관리하는 작업은 세그먼트를 만들고 사용하는 것과 비슷하며, Experience Cloud에 대상자 세그먼트를 공유하는 기능이 추가되었다고 생각하면 됩니다.
샘플 첫 번째 단락(작업):
고객 속성 소스(CSV 및 FIN 파일)를 생성하고 데이터를 업로드하십시오. 준비가 되면 데이터 소스를 활성화할 수도 있습니다. 데이터 소스가 활성화되면 특성 데이터를 Analytics 및 Target에 공유합니다.
첫 단락에 대한 SEO 팁 seo
- 첫 단락에 검색어를 포함하십시오.
- 독자가 사용하는 용어를 사용하십시오.
- 동의어를 포함하고 필요한 경우 이전 용어 사용을 포함하십시오. 예를 들면 “이전에 방문자 ID 또는 MID, MCVID와 같은 약어로 알려진 Experience Cloud ID Service(ECID)는 방문자를 식별하는 범용 영구 ID를 제공합니다.”
- 링크에 SEO 용어를 포함하십시오.
- 복잡한 표에 필수 용어를 배치하지 마십시오. 복잡한 테이블은 신뢰할 수 있는 검색 결과를 내지 않습니다. 이미지의 텍스트는 검색이 아닙니다. 캡션은 검색됩니다.
대문자 사용 capitalization
- Adobe 스타일의 경우 모든 제목, 머리글, 하위 머리글 및 페이지 탐색 요소에서 각 단어 첫 문자에 대문자를 사용합니다.
- 첫 단어와 브랜드 이름, 솔루션 이름, 서비스 이름 등 고유 명사를 제외한 모든 단어는 소문자입니다.
- 도구, 옵션, 메뉴 항목, 대화 상자 및 필드의 제품 이름에서 대소문자를 일치시키십시오.
목차 using-toc
TOC.md는 목차입니다. 안내서마다 하나씩 있어야 합니다.
TOC 에디토리얼 가이드라인
- 대문자 사용: 모든 항목의 각 단어 첫 문자에 항상 대문자를 사용하십시오(두문자어 제외). 공식적인 제품 이름이나 인터페이스 요소(페이지, 탭, 필드, 옵션 등)만 대문자로 표기하십시오. 참조할 때 UI를 일치시키십시오.
- 동사 형태와 병렬법: 명령형 동사를 사용하고 동명사는 피하십시오. TOC는 목록이므로 항상 대부분의 경우 목록을 병렬로 유지하십시오. 때때로 피할 수 없는 예외가 있습니다. 개념 페이지의 경우 명사와 명사구를 사용하십시오. 작업에는 동사를 사용하십시오.
구문 지침
- TOC의 섹션 머리글(상위)은 링크가 될 수 없습니다. 여기에는 콘텐츠가 있는 페이지가 없습니다.
{#processing-rules}와 같은 앵커를 포함해야 합니다. - 목차 섹션 머리글(예:
+ Processing rules {#processing-rules}) 및 목차 문서 링크(예:+ [Article name](article.md))에는 적절한 구문을 사용해야 합니다. - TOC 문서 항목은 문서 제목의 단축 버전일 수 있습니다. 본 문서의 개요, 개념 및 작업 작성에 대한 표준을 따르십시오.
- 동일한 파일을 TOC(또는 여러 TOC)에 여러 번 추가하지 마십시오. 그렇게 하면 이상한 동작이 발생합니다.
- 리포지토리에 여러 사용 안내서가 포함된 경우 사용 안내서 디렉터리는
help디렉터리 내의 하위 디렉터리와 같은 동일한 수준에 있어야 합니다. 각 사용 안내서 디렉터리에는 TOC 파일이 있어야 합니다. 사용 안내서가 중첩되어서는 안 됩니다.
볼드체 및 기울임체 bold
- 절차에서(및 UICONTROL로) 클릭하는 인터페이스 요소에만 볼드체 텍스트를 사용하십시오.
- 강조할 때 또는 기울임체를 사용하지 않으면 단어가 혼란을 줄 수 있을 때 기울임체를 사용하십시오. 예를 들어 외국어일 때, 단어를 설명하거나 용어를 정의할 때입니다.