bpinhosilva/ste-간소화

STE 간소화

개요

ASD-STE100 Simplified Technical English (STE) 의 실용적인 하위 집합을 사용하여 명확하고 모호함이 없는 설명과 지침을 생성합니다.

핵심 원칙: 한 단어, 한 가지 의미; 한 문장, 한 가지 생각; 능동태, 단순 시제.

이는 STE의 하위 집합이지 전체 사양이 아닙니다. 출력에서 ASD-STE100 준수를 주장하지 마십시오.

스타일이 중요한 창의적, 마케팅적, 또는 대화체 산문에는 사용하지 마십시오.

변경하지 않고 유지

다음 항목은 정확히 복사하십시오. 규칙은 이 항목들을 둘러싼 산문에만 적용하십시오:

• 코드, 명령어, 파일 경로, 따옴표로 묶인 값 (예: 'localhost')
• 오류 메시지 및 로그 문자열
• API, 함수, 매개변수, 변수 이름
• 제품 이름, 고유 명사, 버전 번호
• 인용된 텍스트 및 법적 텍스트
• 문서를 다시 작성할 때의 마크다운 구조: 제목, 링크, 표, 코드 블록. 제목, 목록 항목, 표 셀 내부의 산문은 다시 작성하되, 동일한 구조를 유지하십시오.

의미 유지

• 모든 문장의 행위와 대상을 유지하십시오. 원본에서 제공하지 않는 조언, 원인 또는 단계를 추가하지 마십시오.
• 추가할 수 있는 유일한 내용은 기술 용어에 대한 한 문장 정의입니다 (단어 참조).
• 가능성을 표시하려면 if, sometimes, probably 또는 may를 사용하십시오. 가능성을 사실로 절대 바꾸지 마십시오.
• 간단한 단어가 정밀도를 잃는 경우, 원래 단어를 유지하고 정의하십시오.
• 원본에 이상하거나 잘못된 용어가 있는 경우, 원본 표현을 유지하십시오. 텍스트 뒤에 Note: 로 시작하는 한 줄을 추가하여 문제를 명시하십시오. 조용히 수정하지 마십시오.
• 원본에 앞에 목록 없이 *etc.*가 있는 경우, 삭제하십시오.

규칙

1. 단어

• 한 단어, 한 가지 의미. 전체 텍스트에서 같은 대상에 같은 단어를 사용하십시오. 대상을 다른 이름으로 바꾸지 마십시오.

• 간단한 단어를 선택하십시오:

  사용	대신 사용하지 말 것
  use	utilize, employ, leverage
  start	commence, initiate
  stop	cease, terminate, discontinue
  show	demonstrate, indicate, illustrate
  change	modify, alter
  make sure	ensure, ascertain
  help	facilitate, assist
  need, must	require, necessitate
  if	provided that, in the event that
  because	due to the fact that, since, as (이유를 나타낼 때; since는 시간에 대해 올바릅니다)

• 관용구, 속어, 은유, 비유를 사용하지 마십시오. 대상 자체로 설명하십시오.

• 축약형을 사용하지 마십시오. doesn't 대신 does not을 사용하십시오.

• e.g., i.e., etc. 대신 for example, that is, and so on을 사용하십시오.

• 첫 사용 시 기술 용어를 한 문장으로 정의하십시오. 주제가 처음인 독자가 모를 용어일 경우에만 정의하십시오 (예: daemon, write-ahead log). 유지해야 하는 이름은 정의하지 마십시오.

2. 명사

• 명사 클러스터는 최대 3개. 더 긴 연결은 전치사로 분할하십시오.
  • 나쁨: "Run the production database connection pool health check."
  • 좋음: "Check the health of the connection pool for the production database."
• 관사를 유지하십시오 (the, a, an).

3. 동사

• 능동태. 누가 또는 무엇이 행동을 하는지 명시하십시오.
  • 나쁨: "The configuration file is read by the server."
  • 좋음: "The server reads the configuration file."
• 지침에는 명령형을 사용하십시오.
  • 나쁨: "You should restart the service."
  • 좋음: "Restart the service."
• 단순 시제. 단순 현재, 단순 과거, 단순 미래(will read)를 사용하십시오. 진행형(is reading)이나 완료형(has read)을 사용하지 마십시오. Has와 have는 본동사로 사용될 때 올바릅니다(the account has a balance).
• 조동사: would, could, might를 사용하지 마십시오. may는 가능성을 나타낼 때만 사용하십시오. can은 능력을 나타낼 때만 사용하십시오. should는 명령형으로 변경하거나, 행동이 필수인 경우 must로 변경하십시오.
  • 나쁨: "You should back up the database before the upgrade."
  • 좋음: "Back up the database before the upgrade."
• 동명사를 명사로 사용하지 마십시오. 분사가 형용사로 사용되는 것은 올바릅니다(the running process).
  • 나쁨: "Logging errors helps with debugging."
  • 좋음: "Record errors in the log to help you find bugs."

4. 문장과 단락

• 설명: 문장당 최대 25단어. 문장당 하나의 생각.
• 지침: 문장당 최대 20단어. 문장당 하나의 명령(두 동작이 동시에 발생하지 않는 한). 이 제한은 번호가 매겨진 단계 목록의 각 항목에도 적용됩니다.
• 혼합 텍스트: 독자에게 행동을 지시하는 모든 지침에는 20단어 제한을 적용하십시오. 시스템 작동 방식 설명의 단계를 포함한 다른 모든 내용에는 25단어 제한을 적용하십시오.
• 조건문을 먼저 배치하십시오.
  • 나쁨: "Delete the lock file if the process stops."
  • 좋음: "If the process stops, delete the lock file."
• 단락당 최대 6문장. 단락당 하나의 주제.
• 3개 이상의 항목 또는 순차적 단계에는 세로 목록을 사용하십시오.

5. 경고

• 단계가 부상, 데이터 손실 또는 손상을 초래할 수 있는 경우, 해당 단계 앞에 짧은 Warning: 줄을 넣으십시오. 위험을 명시하십시오.
• 하나의 위험이 여러 단계에 적용되는 경우, 첫 번째 단계 앞에 하나의 Warning: 줄을 작성하십시오.

출력 구조

개념 설명 (다음 제목을 이 순서대로 사용하십시오. 선택적 섹션은 규칙에 따라 생략하십시오):

1. 정의: 1–2문장. 그것이 무엇이고 무엇을 하는지 명시하십시오.
2. 작동 방식: 개념에 순서가 있는 프로세스가 있는 경우에만 포함하십시오. 짧은 문장의 번호가 매겨진 목록을 사용하십시오.
3. 핵심 용어: 정의에서 이미 정의한 주요 용어를 제외하고, 새 독자가 모를 기술 용어를 각각 나열하십시오. 각각을 한 문장으로 정의하십시오. 목록이 비어 있으면 이 섹션을 생략하십시오.
4. 예시: 하나의 구체적이고 최소한의 예시. 최대 5문장 또는 5단계.

기존 텍스트 다시 작성: 다시 작성된 텍스트만 출력하고, 의미 유지 규칙이 요구하는 경우 Note: 줄을 추가하십시오. 제목을 사용하지 마십시오. 단계에는 세로 목록을 사용하십시오. 사용자가 요청하지 않는 한 서문이나 변경 목록을 추가하지 마십시오.

독자 수준: 사용자가 독자가 초보자 또는 입문자라고 말하는 경우, 모든 기술 용어를 정의하고 핵심 용어 섹션을 사용하십시오. 사용자가 수준을 제공하지 않으면, 독자가 해당 분야의 기본 사항을 알고 있다고 가정하십시오. 전체 분야가 아닌 특정 아이디어를 설명하십시오.

예시

기존 텍스트 다시 작성

원본:

The deployment pipeline's artifact promotion gating mechanism is being leveraged to ensure that builds which haven't been validated by QA aren't propagated to prod.

다시 작성:

The pipeline blocks builds that QA did not validate. Only validated builds go to production.

개념 설명

요청: "Explain what a database index is."

정의: A database index is a data structure that helps the database find rows quickly. The database keeps the index in addition to the table.

작동 방식:

1. The database copies the values of one or more columns into the index.
2. The database sorts these values and stores a pointer to each row.
3. A query searches the sorted values instead of every row in the table.

핵심 용어:

• 열: 각 테이블 행의 하나의 명명된 필드입니다.
• 포인터: 행의 위치를 제공하는 값입니다.

예시: A users table has one million rows. You add an index on the email column. A query for one email address now reads only a few index entries. Without the index, the query reads all one million rows.

응답 전 자체 점검

초안을 한 번 읽고 각 위반 사항을 수정하십시오:

• 설명이 25단어를 초과하거나, 지침 또는 목록 단계가 20단어를 초과합니까? 분할하십시오.
• 수동태, 진행형 또는 완료 시제, would/could/might, 또는 should가 있습니까? 다시 작성하십시오.
• 동명사가 명사로 사용되었습니까? 간단한 동사를 사용하십시오.
• 명사 클러스터가 3개를 초과합니까? of, for, in 또는 to로 분리하십시오.
• 축약형, 관용구, 비유, 또는 e.g., i.e., *etc.*가 있습니까? 교체하십시오.
• 표의 대신 사용하지 말 것 열에 있는 단어가 있습니까? 사용 열의 단어를 사용하십시오.
• 원본에 포함되지 않은 사실, 단계 또는 원인이 있습니까? 제거하십시오.
• 보호된 텍스트(코드, 이름, 오류, 인용된 값, 마크다운 구조)가 변경되었습니까? 정확히 복원하십시오.
• 한 대상에 두 개의 이름이 있습니까? 하나를 선택하십시오.