Skip to content

Documentation

연구 따위의 필요에 따라 정리·체계화하여 기록된 정보를 원활히 제공하기 위한 일련의 기술. 정보의 수집·분류·색인·초록의 작성, 정보 검색 등. 정보 관리.

Categories

소프트웨어 튜토리얼 작성 규칙

  • Rules for Writing Software Tutorials · Refactoring English
  • 대부분의 소프트웨어 튜토리얼은 중요한 세부사항을 빠뜨리거나 독자의 기대에 맞지 않는 숨겨진 가정을 포함하여 독자가 과정을 재현할 수 없게 만듦
  • 간단한 몇 가지 규칙을 따르면 탁월한 튜토리얼을 작성하는 것이 생각보다 쉬움

규칙:

  1. 초보자를 위한 글쓰기
  2. 명확한 결과를 약속하는 제목 작성
  3. 도입부에서 목표 설명
  4. 최종 결과 미리 보여주기
  5. 복사/붙여넣기 가능한 코드 스니펫 작성
  6. 명령어에서 긴 플래그 사용
  7. 사용자 정의 값과 재사용 가능한 로직 분리
  8. 독자의 수고 줄이기
  9. 코드가 항상 작동 상태로 유지되도록 작성
  10. 하나의 주제만 가르치기
  11. 꾸미기보다 명확성 우선
  12. 종속성 최소화
  13. 파일 이름 명확히 지정
  14. 일관성 있고 설명적인 제목 사용
  15. 솔루션이 작동함을 입증
  16. 완전한 예제 연결

초보자를 위한 글쓰기

  • 튜토리얼의 가장 흔한 실수는 초보자 수준의 개념을 전문가 수준의 용어로 설명하는 것. 대부분의 튜토리얼을 찾는 사람들은 초보자임.
    • 프로그래밍에 초보자가 아닐 수도 있지만 배우고자 하는 도메인에는 초보자임
  • 초보자를 대상으로 작성하며, 전문가 수준의 용어 사용을 지양함
  • 어려운 용어를 피하고 독자가 이해할 수 있는 간단한 언어로 작성
  • 예를 들어 React 튜토리얼에서는 "JSX transpilation" 대신 "React를 사용한 간단한 웹 페이지 생성"과 같은 설명 제공

명확한 결과를 약속하는 제목 작성

  • 제목은 독자가 튜토리얼을 통해 무엇을 배울 수 있는지 구체적으로 전달해야 함
  • 불명확하거나 모호한 제목을 피하고, 기대 결과를 명확히 설명
    • 예: "Build a Real-Time Twitter Clone in 15 Minutes with Phoenix LiveView"

도입부에서 목표 설명

  • 독자가 튜토리얼을 클릭하면, 당신의 말에 관심이 있는 것임. 그러나 계속 읽도록 설득해야 함
  • 독자가 궁금한 것은 두가지
    • 이 기술에 관심을 가져야 하는가?
    • 관심이 있다면, 이 튜토리얼이 나에게 적합한가?
  • 도입부에서 기술의 중요성과 튜토리얼의 유용성을 간결하게 설명
  • 독자가 관심을 가지도록 유용한 정보를 제공하며, 모호한 서술을 지양함
    • 예: Docker 튜토리얼은 Docker가 해결하는 문제와 기대되는 결과를 명확히 설명

최종 결과 미리 보여주기

  • 가능한 한 빨리, 독자가 튜토리얼을 통해 만들게 될 작업 데모나 스크린샷을 보여줄 것
    • 튜토리얼 초반에 최종 결과를 보여주어 목표를 명확히 함
  • 예: 최종 제품의 스크린샷, UI, 동작 예제 등 제공

복사/붙여넣기 가능한 코드 스니펫 작성

  • 독자가 코드를 쉽게 복사하여 편집기나 터미널에 붙여넣기하여 실행할 수 있도록 작성
  • 터미널 프롬프트 문자 $와 같은 불필요한 요소 제거
  • 비대화형 플래그를 사용하여 명령어를 간소화하고, 실패 시 중단되도록 &&를 사용

명령어에서 긴 플래그 사용

  • 명령어에서 짧은 플래그 대신 설명이 명확한 긴 플래그를 사용하여 초보자도 쉽게 이해하도록 작성
    • -r 보다는 --recursive

사용자 정의 값과 재사용 가능한 로직 분리

  • 코드에서 사용자가 수정해야 할 값과 수정하지 말아야 할 코드를 명확히 분리
  • 환경 변수를 사용해 사용자 정의 값을 정의하고 코드의 가독성을 높임

독자의 수고 줄이기

  • 독자가 튜토리얼을 좋아할 수 있도록 그들의 시간을 존중하기
  • 따분한 작업을 하지 않도록 명령어 스니펫으로 대체
    • 예: 수동으로 파일을 수정하는 대신 명령어로 해결

코드가 항상 작동 상태로 유지되도록 작성

  • 예제 코드는 항상 실행 가능해야 하며, 중간 단계에서도 작동 상태를 유지하기
  • 잘못된 코드나 작동하지 않는 예제는 독자에게 혼란을 초래

하나의 주제만 가르치기

  • 튜토리얼은 단일 주제를 중심으로 작성하며, 관련 없는 기술을 혼합하지 않음
  • 예를 들어, 검색 기능을 설명하는 튜토리얼에 불필요한 AI 기술을 추가하지 않음

꾸미기보다 명확성 우선

  • 독자는 장난감 애플리케이션이 아름답게 보이는지 신경 쓰지 않음
  • 불필요한 CSS나 디자인 요소를 최소화하고, 핵심 개념에 집중
  • 복잡한 예제 대신 간단한 코드로 개념을 명확히 전달

종속성 최소화

  • 독자가 설치해야 하는 종속성을 최소화하여 튜토리얼의 접근성을 높임
  • 필수 종속성을 명확히 지정하고, 특정 버전을 명시

파일 이름 명확히 지정

  • 독자에게 수정해야 할 파일 경로와 내용을 정확히 안내
  • 예를 들어, "config 파일에 설정 추가" 대신 전체 파일 경로와 정확히 어느줄을 편집해야 하는지 구체적인 코드 제공

일관성 있고 설명적인 제목 사용

  • 독자가 튜토리얼을 스캔하기 쉽게 구조화된 헤딩 사용
  • 제목을 사용하여 튜토리얼을 구조화하고, 논리적인 구조를 반영하도록 제목을 작성하기
  • 제목의 형식, 시점, 시제를 일관성 있게 유지

솔루션이 작동함을 입증

  • 튜토리얼이 도구 설치나 여러 구성 요소 통합을 가르친다면, 결과를 사용하는 방법을 보여주기
    • 설치 및 통합된 도구의 작동 결과를 독자에게 시각적으로 보여줌
  • 예를 들어, nginx 성공 페이지를 보여주고 URL을 통해 확인 방법 제공

완전한 예제 연결

  • 튜토리얼의 모든 코드를 포함한 레포지토리를 연결하여 전체 흐름을 확인 가능하게 제공
  • 각 단계의 코드를 별도의 git 브랜치로 나누어 독자가 각 단계를 따라갈 수 있도록 함

좋은 글쓰기

좋은 글이란 "소리가 좋은 문장"과 "올바른 아이디어"라는 두 가지 측면을 가질 수 있음

  • 좋은 글은 문장이 잘 흐르거나 올바른 아이디어를 담거나, 혹은 그 두 가지 모두를 충족함
  • 문장 소리의 자연스러움을 추구하는 과정이 아이디어의 정확도와 깊이를 동시에 향상시킴
  • 글을 수정하면서 생기는 제약이 내용을 나쁘게 만들지 않고, 오히려 더 나은 방향으로 이끎
  • 리듬감 있는 문장 구성은 아이디어의 본질에 맞닿아 있어, 읽기 쉽고 검토하기 좋은 글이 됨
  • 내용과 표현의 일치성이 높을수록 정합성과 진실성도 높아지며, 둘은 결국 하나로 연결됨

AI 글쓰기에서 피해야 할 상투적 패턴 모음

  • AI 글쓰기에서 피해야 할 상투적 패턴 모음 | GeekNews
  • AI가 생성한 텍스트에서 반복적으로 나타나는 글쓰기 패턴(trope) 을 카테고리별로 분류한 단일 마크다운 파일
  • 이 파일을 AI 시스템 프롬프트에 추가하면 흔한 AI식 문체를 피하도록 유도할 수 있음
  • 단어 선택, 문장 구조, 문단 구조, 톤, 포맷, 구성 등 6개 대분류 아래 30개 이상의 구체적 패턴을 각각 예시와 함께 정리
  • "delve", "tapestry", "landscape" 같은 AI 특유의 과잉 어휘부터, "It's not X -- it's Y" 같은 거짓 심오함을 만드는 문장 구조까지 포괄
  • 각 패턴은 한두 번 사용하면 괜찮지만 여러 패턴이 동시에 또는 반복적으로 출현할 때 AI 생성 텍스트의 강한 신호가 됨
  • 이 파일 자체도 AI 보조로 작성되었으며, "AI를 위한 AI, 인간을 위한 인간"이라는 면책 조항 포함

단어 선택 (Word Choice)

  • "Quietly"와 마법 부사들: "quietly", "deeply", "fundamentally", "remarkably", "arguably" 등의 부사를 남용해 평범한 묘사에 미묘한 중요성을 부여하는 패턴
    • 예: "quietly orchestrating workflows", "a quiet intelligence behind it"
  • "Delve"와 유사어: 한때 가장 유명한 AI 징후였던 단어로, AI 생성 텍스트에서 비정상적으로 높은 빈도로 등장
    • "certainly", "utilize", "leverage"(동사), "robust", "streamline", "harness" 등이 같은 계열
  • "Tapestry"와 "Landscape": 단순한 단어로 충분한 곳에 거창한 명사를 사용하는 패턴
    • "tapestry"는 상호 연결된 모든 것에, "landscape"는 모든 분야나 도메인에 남용
    • "paradigm", "synergy", "ecosystem", "framework"도 동일 유형
  • "Serves As" 회피: 단순한 "is/are" 대신 "serves as", "stands as", "marks", "represents" 같은 과장된 연결어 사용
    • AI의 반복 페널티가 기본 계사(copula) 대신 화려한 구문 쪽으로 밀어내기 때문에 발생

문장 구조 (Sentence Structure)

  • 부정 병렬 구문(Negative Parallelism): "It's not X -- it's Y" 패턴으로, AI 글쓰기에서 가장 흔하게 식별되는 징후
    • 모든 것을 놀라운 재구성(reframe)으로 포장해 거짓 심오함을 생성
    • LLM 이전에는 이런 방식의 대량 글쓰기가 존재하지 않았음
    • "not because X, but because Y"라는 인과적 변형도 포함
  • "Not X. Not Y. Just Z.": 두 가지 이상을 부정한 뒤 실제 요점을 드러내는 드라마틱 카운트다운 패턴
    • 진실을 좁혀가는 듯한 거짓 느낌을 생성
  • "The X? A Y.": 아무도 묻지 않은 질문을 스스로 던지고 바로 답하는 수사적 질문-즉답 패턴
    • 극적 효과를 위해 사용하며, AI가 이를 훌륭한 글쓰기의 정수로 간주
  • 반복 어구(Anaphora) 남용: 동일한 문장 시작을 빠르게 여러 번 반복
    • 예: "They assume that... They assume that... They assume that..."
  • 삼중 구문(Tricolon) 남용: 셋의 규칙을 과용하며 넷이나 다섯으로 확장하는 경우도 포함
    • 하나의 삼중 구문은 우아하지만, 연속 세 개는 패턴 인식 실패
  • "It's Worth Noting": 아무 신호도 보내지 않는 채움 전환어
    • "It bears mentioning", "Importantly", "Interestingly", "Notably"도 동일 유형
    • 새로운 논점을 이전 논증과 실제로 연결하지 않으면서 도입
  • 피상적 분석(Superficial Analyses): 문장 끝에 현재 분사("-ing") 구문을 붙여 얕은 분석을 주입
    • "highlighting its importance", "reflecting broader trends", "contributing to the development of..." 같은 표현
    • 평범한 사실에 중요성, 유산, 광범위한 의미를 부여
  • 거짓 범위(False Ranges): "from X to Y"에서 X와 Y가 실제 어떤 스케일 위에 있지 않은 구문
    • 정당한 사용에서는 의미 있는 중간 지점이 있는 스펙트럼을 암시하지만, AI는 느슨하게 관련된 두 가지를 나열하는 데 사용
  • 동명사 단편 나열(Gerund Fragment Litany): 주장 후 주어 없는 동명사 단편을 연속으로 나열
    • "Fixing small bugs. Writing straightforward features. Implementing well-defined tickets."
    • 첫 문장이 이미 전부를 말했고, 단편들은 단어 수와 AI 특유의 리듬만 추가
    • 인간은 초고를 이런 식으로 작성하지 않으며, 순수한 구조적 틱(tic)

문단 구조 (Paragraph Structure)

  • 짧은 펀치 단편(Short Punchy Fragments): 매우 짧은 문장이나 문장 단편을 독립 문단으로 사용해 인위적 강조 생성
    • RLHF 훈련이 최저 수준 독자를 겨냥한 "가독성을 위한 글쓰기" 쪽으로 모델을 밀어낸 결과
    • 한 문장에 하나의 생각, 정신적 상태 유지 불필요한 비인간적 스타일
  • 변장한 리스티클(Listicle in a Trench Coat): 번호 매기거나 라벨 붙인 포인트를 연속 산문으로 위장
    • "The first... The second... The third..."로 시작하는 문단으로 리스트 형식을 숨기는 패턴
    • 리스트 생성을 중단하라고 지시받은 후 대안으로 채택하는 경우가 많음

톤 (Tone)

  • "Here's the Kicker": 계시를 약속하지만 그 빌드업이 필요 없는 포인트를 전달하는 거짓 서스펜스 전환
    • "Here's the thing", "Here's where it gets interesting", "Here's what most people miss"도 동일 유형
  • "Think of It As...": 독자가 무엇이든 이해하려면 비유가 필요하다고 가정하는 교사 모드 기본값
    • AI가 원래 개념보다 덜 명확한 비유를 생성하는 경우가 빈번
  • "Imagine a World Where...": AI의 전형적 미래주의 초대로, "Imagine" 뒤에 전제에 동의하면 일어날 훌륭한 일들의 목록이 나옴
  • 거짓 취약성(False Vulnerability): 제4의 벽을 깨거나 편향을 인정하는 척하는 수행적 자기 인식
    • 실제 취약성은 구체적이고 불편하지만, AI의 취약성은 세련되고 위험이 없음
  • "The Truth Is Simple": 실제로 증명하는 대신 무언가가 명백하거나 단순하다고 주장하는 패턴
  • 웅장한 스테이크 인플레이션(Grandiose Stakes Inflation): 모든 논점의 이해관계를 세계사적 중요성으로 부풀림
    • API 가격에 대한 블로그 포스트가 문명의 운명에 대한 명상이 되는 현상
  • "Let's Break This Down": 전문가 독자에게도 교사-학생 관계를 기본값으로 설정하는 교수법적 목소리
    • "Let's unpack this", "Let's explore", "Let's dive in"도 동일 유형
  • 모호한 귀속(Vague Attributions): 구체적 출처 없이 "experts", "observers", "industry reports" 등 이름 없는 권위에 주장을 귀속
    • 한 사람이 말한 것을 널리 퍼진 견해로, 두 곳의 출처를 "several publications"로 부풀리는 행태도 포함
  • 만들어낸 개념 라벨(Invented Concept Labels): 추상적 문제 명사(paradox, trap, creep, divide, vacuum, inversion)를 도메인 단어에 붙여 분석적으로 들리지만 근거 없는 합성 라벨 생성
    • "supervision paradox", "acceleration trap", "workload creep" 등
    • 이름을 붙이고 논증은 건너뛰는 수사적 약칭으로 기능하며, 같은 글에 여러 개 등장하면 AI slop의 강한 신호

포맷 (Formatting)

  • 엠 대시 중독(Em-Dash Addiction): 극적 일시 정지, 삽입어, 전환점에 엠 대시를 강박적으로 과용
    • 인간 작가는 글 하나에 2~3개를 자연스럽게 사용하지만, AI는 20개 이상 사용
  • 굵게-먼저 불릿(Bold-First Bullets): 모든 불릿 포인트가 굵은 구문으로 시작하는 패턴
    • Claude와 ChatGPT 마크다운 출력에서 매우 흔하며, 수동 작성 시 거의 아무도 이렇게 포맷하지 않음
    • AI 생성 문서, 블로그 포스트, README 파일(특히 이모지 포함)의 확실한 징후
  • 유니코드 장식(Unicode Decoration): 유니코드 화살표(→), 스마트/곱슬 인용부호 등 표준 키보드로 쉽게 입력할 수 없는 특수 문자 사용
    • 실제 작가는 텍스트 에디터에서 직선 인용부호와 ->, =>를 사용
    • Claude가 특히 → 화살표를 선호

구성 (Composition)

  • 프랙탈 요약(Fractal Summaries): "앞으로 말할 것, 지금 말하는 것, 방금 말한 것"을 문서의 모든 수준에서 적용
    • 모든 하위 섹션, 섹션, 문서 자체에 각각 요약이 붙음
  • 죽은 비유(The Dead Metaphor): 하나의 비유에 고착해 전체 글에서 반복적으로 사용
    • 인간 작가는 비유를 도입하고 사용한 뒤 넘어가지만, AI는 5~10회 반복
  • 역사적 비유 쌓기(Historical Analogy Stacking): 기술 글쓰기에서 특히 흔하며, 역사적 기업이나 기술 혁명을 빠르게 나열해 거짓 권위를 구축
    • "Apple didn't build Uber. Facebook didn't build Spotify..." 류의 패턴
  • 한 포인트 희석(One-Point Dilution): 단일 논점을 10가지 다른 방식으로 수천 단어에 걸쳐 재진술
    • 다른 비유, 예시, 프레이밍으로 같은 아이디어를 반복해 "포괄적"으로 보이게 패딩
  • 콘텐츠 복제(Content Duplication): 같은 글 안에서 전체 섹션이나 문단을 그대로 반복
    • 모델이 이미 작성한 내용을 추적하지 못할 때, 특히 긴 글에서 발생
    • 편집되지 않은 AI 출력의 확실한 징후이지만 최근에는 덜 흔함
  • 표지판 결론(The Signposted Conclusion): "In conclusion", "To sum up", "In summary"로 결론을 명시적으로 알림
    • 능숙한 글쓰기는 결론을 독자가 느끼게 하며 알려줄 필요 없음
    • AI가 템플릿을 따르기 때문에 구조적 움직임을 신호로 보냄
  • "Despite Its Challenges...": AI가 문제를 인정하되 즉시 기각하는 경직된 공식
    • "Despite its [긍정적 단어], [주어] faces challenges..." 후 "Despite these challenges, [낙관적 결론]"으로 항상 동일한 비트를 따름

핵심 원칙

  • 위 패턴들은 한 번 사용하면 괜찮을 수 있지만, 여러 패턴이 함께 나타나거나 하나의 패턴이 반복 사용될 때 문제가 됨
  • 인간처럼 쓸 것: 다양하고, 불완전하고, 구체적으로

See also

Favorite site

Best Practices