개발자를 위한 기술 문서 작성

HTML, CSS, JavaScript, Python, PHP, C++, Dart — 너무 많은 프로그래밍 언어가 있으며 그 중 일부에 완전히 유창할 수도 있습니다! 그러나 우리가 더 많은 코드를 더 잘 작성하는 것을 목표로 함에 따라 일상 언어로 작성하고 의사 소통하는 방식이 점점 더 중요해지고… 어쩌면 간과될 수도 있습니다.

우리가 코드에 대해 작성하는 방식은 틀림없이 코드 자체만큼 중요합니다. 그리고 당신이 그 선에 속해 있음에도 불구하고 우리 모두는 우리의 말이 코드의 효율성에 도움이 될 수도 있고 해칠 수도 있다는 데 동의할 수 있습니다.

이 기사에서 저는 이 두 가지 겉보기에 별개의 분야인 프로그래밍과 쓰기가 어떻게 결합되어 개발자 기술을 다음 단계로 끌어올릴 수 있는지 간략하게 설명하고 싶습니다.

잠깐, 기술 문서? 네, 바로 그 뜻입니다. 나는 진정으로 우리 모두가 어떤 의미에서 작가라고 믿습니다. 그리고 저는 여러분을 더 나은 개발자이자 커뮤니케이터로 만들 수 있는 방법에 대한 작성 팁, 조언 및 예제가 포함된 입문서를 제공하려고 합니다.

테크니컬 라이팅은 어디에나 있다

작년에 인기 있는 Mac Git 클라이언트인 Tower를 개발한 팀은 4,000명 이상의 개발자를 대상으로 설문조사 그리고 그들 중 거의 50%가 하루에 3-6시간 동안 코드를 작성하는 데 소비한다는 사실을 발견했습니다.

그리고 예, 그것은 꽤 틈새 그룹을 대상으로 한 설문 조사이지만 우리 중 많은 사람들이 그 범위에 속한다고 생각합니다. 어떤 경우이든 개발자는 연중무휴로 코드를 작성하지 않습니다. 이 설문조사에서 알 수 있듯이 우리는 다른 일을 하는 데 많은 시간을 할애하고 있기 때문입니다.

여기에는 다음이 포함될 수 있습니다.

• 새로운 기능을 시연하고,
• 새로운 기능을 문서화하고,
• 새로운 기능과 관련된 작업 티켓 업데이트, 또는
• 새 기능을 지원하기 위해 백로깅 작업을 수행합니다.

물론, 화장실 쉬는 시간과 Wordle도 항상 있습니다.

어쨌든, 우리가 일반적으로 하는 일의 대부분은 팀, 동료, 클라이언트, 사용자 및 기타 개발자와 같은 사람들과 의사 소통하는 것과 관련됩니다.

그래서 우리는 많은 시간을 다음을 통해 인간과 의사 소통하는 데 보냅니다. 말 컴퓨터와 통신하는 것 외에도 암호. 단어는 서면 언어입니다. 그리고 우리가 우리의 말을 더 잘 쓴다면, 우리는 더 잘 소통할 것입니다. 우리가 더 잘 의사소통할 때, 우리는 우리가 원하는 것을 얻을 가능성이 더 높아집니다.

테크니컬 라이팅 101입니다.

그리고 여기서 끝이 아닙니다. 일부 프로그래머는 또한 자신의 제품을 만드는 것을 좋아합니다. 즉, 마케팅을 업무의 일부로 만들어야 합니다. 테크니컬 라이팅도 거기에서 큰 역할을 합니다. 그래. 나는 기술적인 글쓰기가 참으로 어디에나.

좋은 문법이란?

너무 많은 프로그래밍 언어가 있으므로 마지막으로 원하는 것은 다른 언어를 배우는 것입니다.

문법 영어의 필수적인 부분이며 의사 소통의 잠재력을 최대한 발휘합니다. 그것은 우리를 보다 형식적이고 전문적이며 일관성 있게 만듭니다.

언어에 대한 간략한 설명을 드리겠습니다.

영어 구문

프로그래밍 언어와 마찬가지로 영어는 구문이 잘 정의되어 있으며 단어로 시작합니다.

단어는 영어의 구성 요소이며 XNUMX가지 버킷으로 나뉩니다.

다음과 같이 생각하십시오. UI 구성 요소: 완전하고 강력한 문장을 구성하는 것과 같은 방식으로 이동할 수 있는 모듈식 조각입니다. UI. 모든 구성 요소가 항상 있어야 합니까? 확실히! 인터페이스에서와 마찬가지로 경험을 완료하는 데 필요한 조각으로 문장을 구성하십시오.

목소리와 톤

어휘, 구두점, 문장 구조 및 단어 선택. 이것이 영어의 모든 요소입니다. 우리는 아이디어를 공유하고, 친구 및 가족과 의사 소통하고, 동료에게 이메일을 보내는 데 사용합니다.

그러나 다음을 고려하는 것이 중요합니다. 소리 우리의 메시지의. 느낌표 하나로 메시지의 어조를 완전히 바꿀 수 있다는 것은 놀랍습니다.

1. 나는 프로그래밍을 좋아한다.
2. I 처럼 프로그램 작성! :)

목소리와 톤을 혼동하기 쉽고 그 반대의 경우도 마찬가지입니다.

목소리 문맥에 따라 달라지는 단어 선택에 관한 것입니다. 예를 들어, 초보자를 위한 튜토리얼은 속어와 비격식적인 언어를 사용하여 친근한 목소리를 전달하는 반면, 문서는 요점을 바로 잡기 위해 공식적이고 진지하며 전문적인 방식으로 작성될 수 있습니다.

두 가지 다른 목소리로 쓰여진 같은 메시지:

• 재미 : "소셜 네트워크를 확장하고 현재 트렌드에 대한 최신 정보를 얻으십시오."
• 심각한: "가장 큰 소셜 네트워킹 앱 및 온라인 구인 시장 중 하나에서 일자리를 찾으십시오."

무례하고 공격적이며 프로답지 못한 것처럼 보이는 메시지를 실수로 작성하는 것은 드문 일이 아닙니다. 여기는 음정 놀이로 제공됩니다. 큰 소리로 메시지 읽기, 다른 사람들이 대신 읽게 하고 구두점과 문장 구조를 실험해 보세요. 그렇게 해서 톤을 연마합니다.

생각하는 또 다른 방법이 있습니다. 당신의 목소리는 결코 변하지 않지만 당신의 어조는 변합니다. 당신의 목소리는 당신이 어떤 사람인지와 비슷하지만 어조는 주어진 상황에서 당신이 어떻게 반응하는지입니다.

능동태와 수동태

문장에는 항상 행위자, 동사 및 대상이 포함됩니다. 이것들이 오는 순서에 따라 문장이 능동태로 쓰여졌는지 수동태로 쓰여졌는지 결정됩니다.

배우가 먼저 나온다. 능동태의 목소리. 예: "CSS는 배경을 그립니다."

능동태를 ​​사용하는 문장은 대응하는 문장보다 더 간단합니다. 더 명확하고 짧고 이해하기 쉬우며 요점을 정확히 전달하는 보다 전문적인 음성에 적합합니다.

와 수동태, 배우가 마지막에 옵니다. (내가 그곳에서 무엇을 했는지 보셨나요?) 이것은 우리 액터(이 경우 CSS)가 마지막에 다음과 같이 온다는 것을 의미합니다. "배경은 CSS로 칠해져 있습니다."

독자는 일반적으로 머리 속에서 수동태를 능동태로 변환하므로 처리 시간이 더 오래 걸립니다. 능동태로 글을 쓰는 것이 더 낫다는 말을 들어본 적이 있다면 대개 이것이 그 이유입니다. 기술 작가는 연구 인용과 같은 극히 일부 예외를 제외하고 대부분의 경우 능동태를 선호합니다.

하지만 그렇다고 해서 항상 능동적인 목소리를 위해 노력해야 하는 것은 아닙니다. 동일한 단락에서라도 하나에서 다른 것으로 전환하면 효과적으로 사용하면 한 문장에서 다른 문장으로 콘텐츠 흐름을 더 원활하게 만들 수 있습니다.

실수 방지

문법은 언어의 구조와 정확성에 관한 것이며 문서를 빠르게 교정하는 것보다 더 좋은 것은 없습니다. 철자 오류, 문법 문제 및 의미상의 불완전성을 글에서 제거하는 것이 매우 중요합니다.

이 기사의 끝에서 나는 전문가들이 쓰기 실수를 피하기 위해 사용하는 귀중한 도구를 보여줄 것입니다. 분명히, 요즘에는 거의 모든 것에 맞춤법 검사기가 내장되어 있습니다. 우리의 코드 편집기에는 실수를 방지하는 데 도움이 되는 맞춤법 검사 및 린트 플러그인도 있습니다. 

하지만 문법에 관한 모든 것을 한번에 해결할 수 있는 도구를 찾고 계시다면, 문법 가장 널리 사용되는 도구 중 하나입니다. 나는 그것에 대한 리베이트를받지 않습니다. Emmet, eslint 또는 기타 린터를 사용하여 깨끗하고 명확한 코드를 작성하는 것과 유사하게 많은 편집자와 작성자가 깨끗하고 명확한 콘텐츠를 작성하는 데 사용하는 정말 훌륭한 도구입니다.

코드 주석 작성

우리가 다른 개발자를 위해 작성하는 내용은 코드에 작성하는 내용이든, 코드를 설명하는 방법이든, 코드 조각에 대한 피드백을 제공하는 방법이든 전체 작업 품질에 큰 영향을 미칠 수 있습니다.

모든 프로그래밍 언어에 주석을 작성하기 위한 표준 기능 세트가 제공된다는 점은 흥미롭습니다. 그들은 코드가 무엇을 하는지 설명해야 합니다. 그렇다고 해서 다음과 같은 막연한 의견을 말하는 것은 아닙니다.

red *= 1.2 // Multiply `red` by 1.2 and re-assign it

대신 추가 정보를 제공하는 주석을 사용하십시오.

red *= 1.2 // Apply a 'reddish' effect to the image

컨텍스트에 관한 모든 것입니다. “나는 어떤 프로그램을 만들고 있는가?” 당신이 스스로에게 물어야 할 질문의 종류입니다.

댓글은 가치를 더해야 합니다.

무엇이 "좋은" 코드 주석을 만드는지 살펴보기 전에 다음은 게으른 주석의 두 가지 예입니다.

const age = 32 // Initialize `age` to 32

filter: blur(32px); /* Create a blur effect with a 32px radius */

주석의 목적은 코드를 반복하는 것이 아니라 코드에 가치를 추가하는 것임을 기억하십시오. 그렇게 할 수 없다면 코드를 있는 그대로 두는 것이 좋습니다. 이러한 예제를 "게으른" 것으로 만드는 것은 코드가 분명히 수행하는 작업을 다시 설명하기 때문입니다. 이 경우 주석은 우리가 이미 알고 있는 것을 말해주기 때문에 중복됩니다. 가치를 추가하지 않습니다!

주석은 현재 코드를 반영해야 합니다.

오래된 주석은 대규모 프로젝트에서 드문 일이 아닙니다. 감히 말하다 가장 프로젝트.

프로그래머이자 함께 어울릴 수 있는 만능의 멋진 사람인 David를 상상해 봅시다. David는 문자열 목록을 A에서 Z까지 알파벳순으로 정렬하기를 원하므로 JavaScript에서 명백한 작업을 수행합니다.

cities = sortWords(cities) // sort cities from A to Z

그런 다음 David는 sortWords()가 실제로 목록을 Z에서 A로 정렬한다는 것을 깨달았습니다. 단순히 출력을 뒤집을 수 있으므로 문제가 되지 않습니다.

cities = sortWords(cities) // sort cities from A to Z
cities = reverse(cities)

불행히도 David는 코드 주석을 업데이트하지 않았습니다.

이제 내가 이 이야기를 하지 않았다고 상상해보세요. 그리고 당신이 본 것은 위의 코드뿐입니다. 코드의 두 번째 줄을 실행하면 `cities`가 Z에서 A로 정렬될 것이라고 자연스럽게 생각할 것입니다! 이 모든 혼란의 실패는 오래된 댓글로 인해 발생했습니다.

이것은 과장된 예일 수 있지만 마감 기한을 두고 경쟁하는 경우 비슷한 일이 발생할 수 있습니다(그리고 종종 발생합니다). 고맙게도 이것은 하나의 간단한 규칙을 따르면 예방할 수 있습니다... 코드를 변경할 때 주석을 변경하십시오.

그것은 당신과 당신의 팀을 많은 위험으로부터 구할 간단한 규칙입니다. 기술 부채.

잘못 작성된 주석이 어떻게 생겼는지 알았으니 이제 몇 가지 좋은 예를 살펴보겠습니다.

주석은 단일 관용어 코드를 설명해야 합니다.

때로는 자연스러운 하는 방식이 옳지 않습니다. 프로그래머는 표준을 약간 "파기"해야 할 수도 있지만 그렇게 할 때 근거를 설명하는 약간의 설명을 남기는 것이 좋습니다.

 function addSetEntry(set, value) {    
  /* Don't return `set.add` because it's not chainable in IE 11. */  
  set.add(value);
  return set;
}

도움이 되겠죠? 당신이 이 코드를 검토할 책임이 있다면, 무슨 일이 일어나고 있는지 설명하는 주석 없이 그것을 수정하고 싶은 유혹을 받았을 것입니다.

댓글은 미래 작업을 식별할 수 있습니다.

댓글로 할 수 있는 또 다른 유용한 작업은 해야 할 일이 더 많다는 것을 인정하는 것입니다.

// TODO: use a more efficient algorithm
linearSort(ids)

이렇게 하면 흐름에 집중할 수 있습니다. 그리고 나중에 당신(또는 다른 누군가)이 돌아와서 고칠 수 있습니다.

댓글은 소스로 다시 링크될 수 있습니다.

따라서 StackOverflow에서 문제에 대한 해결책을 찾았습니다. 해당 코드를 복사하여 붙여넣은 후 나중에 참조할 수 있도록 도움이 된 답변에 대한 링크를 유지하는 것이 때때로 좋은 방법입니다.

// Adds handling for legacy browsers
// https://stackoverflow.com/a/XXXXXXX

이는 솔루션이 변경될 수 있기 때문에 중요합니다. 코드가 깨질 경우에 대비하여 코드가 어디에서 왔는지 아는 것이 항상 좋습니다.

풀 리퀘스트 작성

Pull 요청 (PRs) 모든 프로젝트의 기본적인 측면입니다. 그들은 코드 리뷰의 핵심입니다. 그리고 코드 검토는 좋은 표현 없이 팀의 성과에 빠르게 병목 현상이 될 수 있습니다.

좋은 PR 설명 요약 뭐 변화가 일어나고 있고 why 만들어지고 있습니다. 대규모 프로젝트에는 다음과 같은 풀 리퀘스트 템플릿이 있습니다. 실제 예:

## Proposed changes
Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request.

## Types of changes
What types of changes does your code introduce to Appium?
 - [ ] Bugfix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
 - ...

## Checklist
 - [ ] I have read the CONTRIBUTING doc
 - [ ] I have signed the CLA
 - [ ] Lint and unit tests pass locally with my changes

## Further comments
If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc…

모호한 것을 피하십시오 PR 제목들

다음과 같은 제목은 피하세요.

• 빌드 수정.
• 버그 수정
• 패치를 추가합니다.

이것들은 심지어 시도 우리가 다루고 있는 빌드, 버그 또는 패치를 설명합니다. 빌드의 어떤 부분이 수정되었는지, 어떤 버그가 수정되었는지 또는 어떤 패치가 추가되었는지에 대한 약간의 추가 세부 정보는 동료와 더 나은 의사 소통 및 협업을 구축하는 데 큰 도움이 될 수 있습니다. 그것은 수준을 설정하고 같은 페이지에 사람들을 가져옵니다.

PR 제목은 전통적으로 명령형. 전체 내용을 한 줄로 요약한 것입니다. PR, 그리고 그들은 설명해야합니다 뭐 에 의해 수행되고 있습니다. PR.

다음은 몇 가지 좋은 예입니다.

• NgOptimizedImage에서 사용자 정의 srcset 속성 지원
• 75% 이미지 품질로 기본 이미지 구성
• 모든 기본 제공 ControlValueAccessors에 대한 명시적 선택기를 추가합니다.

오래 피하다 PRs

큰 PR 엄청난 설명을 의미하며 아무도 수백 또는 수천 줄의 코드를 검토하고 싶어하지 않으며 때로는 전체를 무시합니다!

대신 다음을 수행할 수 있습니다.

• 통해 팀과 의사 소통 문제,
• 계획을 세우고,
• 문제를 더 작은 조각으로 나누거나
• 각각의 조각을 따로 따로 작업하다 PR.

이제 훨씬 깨끗하지 않습니까?

에 세부사항을 제공하십시오 PR 몸

달리 PR 제목 본체는 전에, 다음을 포함한 모든 세부 사항을 위한 장소:

• 왜 PR 끝 나가고있다?
• 이것이 최선의 접근 방식인 이유는 무엇입니까?
• 접근 방식의 모든 단점 및 가능한 경우 이를 해결하기 위한 아이디어
• 버그 또는 티켓 번호, 벤치마크 결과 등

버그보고

버그 보고서는 모든 프로젝트에서 가장 중요한 측면 중 하나입니다. 그리고 모든 훌륭한 프로젝트는 사용자 피드백을 기반으로 합니다. 일반적으로 수많은 테스트를 거친 후에도 대부분의 버그를 찾는 것은 사용자입니다. 사용자는 또한 훌륭한 이상주의자이며 때로는 기능 아이디어가 있습니다. 그들의 말을 들어주세요!

기술 프로젝트의 경우 이 모든 작업은 문제 보고를 통해 수행됩니다. 잘 작성된 문제는 다른 개발자가 쉽게 찾고 응답할 수 있습니다.

예를 들어, 대부분의 대규모 프로젝트에는 틀:

 <!-- Modified from angular-translate/angular-translate -->
 ### Subject of the issue
 Describe your issue here.

 ### Your environment
 * version of angular-translate
 * version of angular
 * which browser and its version

 ### Steps to reproduce
 Tell us how to reproduce this issue.

 ### Expected behavior
 Tell us what should happen.

 ### Actual behavior
 Tell us what happens instead.

스크린샷 수집

다음을 사용하여 문제를 캡처합니다. 시스템의 화면 촬영 유틸리티.

스크린샷이라면 CLI 프로그램에서 텍스트가 명확한지 확인하십시오. 만약 UI 프로그램에서 스크린샷이 올바른 요소와 상태를 캡처하는지 확인하십시오.

문제를 설명하기 위해 실제 상호 작용을 캡처해야 할 수도 있습니다. 그렇다면 시도하십시오. 화면 녹화 도구를 사용하여 GIF 녹화.

문제를 재현하는 방법

프로그래머가 버그가 컴퓨터에 있을 때 버그를 해결하는 것이 훨씬 쉽습니다. 그렇기 때문에 좋은 커밋에는 문제를 정확하게 재현하는 단계가 수반되어야 합니다.

다음 예는 다음과 같습니다

Update: you can actually reproduce this error with objects:

 ```html
 <div *ngFor="let value of objs; let i = index">
   <input [ngModel]="objs[i].v" (ngModelChange)="setObj(i, $event)" />
 </div>
 ```

 ```js
 export class OneComponent {
   obj = {v: '0'};
   objs = [this.obj, this.obj, this.obj, this.obj];
 ​
  setObj(i: number, value: string) {
     this.objs[i] = {v: value};
  }
 }
 ```

 The bug is reproducible as long as the trackBy function returns the same value for any two entries in the array. So weird behavior can occur with any duplicate values.

원인 제안

당신은 버그를 잡은 사람이므로 버그가 있는 이유에 대한 몇 가지 잠재적인 원인을 제안할 수 있습니다. 버그는 특정 이벤트가 발생한 후에만 발생하거나 모바일에서만 발생할 수 있습니다.

또한 코드베이스를 탐색하고 문제를 일으키는 원인을 식별하는 것도 나쁘지 않습니다. 그러면 귀하의 문제가 훨씬 빨리 종료되고 관련 PR.

고객과의 커뮤니케이션

솔로 프리랜서로 일할 수도 있고 소규모 팀의 수석 개발자일 수도 있습니다. 두 경우 모두 프로젝트에서 고객과의 인터페이스를 담당한다고 가정해 보겠습니다. 

이제 프로그래머의 고정 관념은 우리가 의사 소통을 잘 못한다는 것입니다. 우리는 지나치게 기술적인 전문 용어를 사용하고, 무엇이 가능하고 불가능한지를 다른 사람들에게 알리고, 누군가가 우리의 접근 방식에 의문을 제기하면 방어적인 태도를 취하는 것으로 알려져 있습니다.

그렇다면 어떻게 그 고정관념을 완화할 수 있을까요? 고객에게 원하는 것이 무엇인지 묻고 항상 고객의 피드백에 귀를 기울이십시오. 방법은 다음과 같습니다.

올바른 질문을하십시오

귀하와 클라이언트가 동일한 페이지에 있는지 확인하여 시작하십시오.

• 타겟 고객은 누구입니까?
• 사이트의 목표는 무엇입니까?
• 가장 가까운 경쟁자는 누구이며 그들이 올바르게 하고 있는 것은 무엇입니까?

질문을 하는 것도 긍정적으로 글을 쓰는 좋은 방법입니다. 특히 고객의 피드백이나 결정에 동의하지 않는 상황에서는 더욱 그렇습니다. 질문을 하면 상대방이 자신의 입장을 옹호하여 공격하는 것이 아니라 자신의 주장을 지지하게 됩니다.

• 추가 성능 비용이 발생하더라도 괜찮습니까?
• 구성 요소를 이동하면 목표를 더 잘 달성하는 데 도움이 됩니까?
• 좋습니다. 출시 후 유지 관리 책임은 누구에게 있습니까? 
• 이 두 색상의 대비가 WCAG AA 표준을 통과하는지 직접 알고 계십니까?

질문은 훨씬 더 순수하고 적개심에 대한 호기심을 조장합니다.

자신을 판매

잠재 고객에게 프레젠테이션을 하는 경우 고객을 고용하도록 설득해야 합니다. 클라이언트가 당신을 선택해야 하는 이유는 무엇입니까? 다음을 지정하는 것이 중요합니다.

• 너 누구 니?
• 당신이 할
• 당신이 그 직업에 적합한 이유
• 수행한 관련 작업에 대한 링크

그리고 일단 일자리를 얻고 계약서를 작성해야 하는 경우, 법률가들의 무리보다 더 위협적인 내용은 없다는 것을 기억하십시오. 디자인 프로젝트를 위해 작성되었지만 청부 살인자 훨씬 친근한 글을 쓰기 위한 좋은 출발점이 될 수 있습니다.

세부 사항에 대한 귀하의 관심은 귀하와 동일한 프로젝트에서 승리하려는 다른 개발자의 차이일 수 있습니다. 내 경험에 따르면 고객은 기술적으로 가장 유능하거나 해당 업무에 경험이 있는 사람보다 함께 일하기 좋아할 것이라고 생각하는 개발자를 쉽게 고용할 것입니다.

마이크로카피 쓰기

축소 복사 사용자 친화적 인 글쓰기의 기술입니다. UI 오류와 같은 메시지. 개발자로서 오류 메시지를 작성해야 했던 적이 있을 것입니다. 오류 메시지는 시작 시간까지 백버너에 놓였기 때문입니다.

이것이 때때로 다음과 같은 오류가 표시되는 이유일 수 있습니다.

Error: Unexpected input (Code 693)

오류는 사용자가 처리하기를 바라는 마지막 것입니다. 하지만 그런 일이 일어나기 때문에 우리가 할 수 있는 일은 없습니다. 다음은 현미경 기술을 향상시키기 위한 몇 가지 팁입니다.

전문 용어 피하기

대부분의 사람들은 서버가 무엇인지 모르지만 프로그래머는 100% 알고 있습니다. 그렇기 때문에 오류 메시지에 다음과 같은 흔하지 않은 용어가 표시되는 것은 드문 일이 아닙니다. API 또는 "시간 초과 실행".

기술 클라이언트나 사용자 기반을 다루지 않는 한 대부분의 사용자는 컴퓨터 과학 과정을 수강하지 않았고 인터넷이 어떻게 작동하는지, 그리고 왜 특정 기능이 작동하지 않는지 모릅니다. 따라서 오류.

따라서 좋은 오류 메시지는 why 이러한 설명에는 무서운 기술 용어를 사용해야 할 수 있기 때문에 문제가 발생했습니다. 그렇기 때문에 전문 용어를 사용하지 않는 것이 매우 중요합니다.

사용자를 비난하지 마십시오

상상해보십시오. 귀하의 플랫폼에 로그인하려고합니다. 그래서 저는 브라우저를 열고 귀하의 웹사이트를 방문하여 제 세부 정보를 입력합니다. 그런 다음 "이메일/비밀번호가 올바르지 않습니다."라는 메시지가 표시됩니다.

이 메시지가 적대적이라고 생각하는 것이 드라마틱해 보이지만 무의식적으로 나를 바보로 만든다. Microcopy는 사용자를 비난하는 것은 결코 옳지 않다고 말합니다. Mailchimp의 로그인을 수정한 이 예와 같이 덜 직관적인 메시지로 메시지를 변경해 보십시오. “죄송합니다. 이메일-비밀번호 조합이 올바르지 않습니다. 계정 복구를 도와드리겠습니다.”

나는 또한 모든 대문자와 느낌표를 피하는 것의 중요성을 추가하고 싶습니다! 물론, 그들은 흥분을 전달하는 데 사용될 수 있지만, 마이크로카피에서는 사용자에 대한 적대감을 만듭니다.

사용자를 압도하지 마십시오

현미경 사본에 유머를 사용하는 것은 좋은 생각입니다! 기분을 밝게 할 수 있으며 최악의 오류로 인한 부정적인 감정을 억제하는 쉬운 방법입니다.

하지만 사용하지 않는다면 아주, 사용자를 모욕하고 모욕하는 것처럼 보일 수 있습니다. 그건 그냥 큰 감수할 위험.

Mailchimp는 다음과 같이 잘 말합니다.

농담을 하려고 일부러 나가지 마세요. 억지로 유머를 하는 것은 아예 하지 않는 것보다 나쁠 수 있습니다. 확신이 서지 않으면 똑바로 얼굴을 유지하십시오..

(강조 광산)

접근 가능한 마크업 작성

우리는 접근성과 그것이 기술적인 글쓰기와 어떻게 관련되는지에 대한 전체 기사를 쉽게 보낼 수 있습니다. 젠장, 접근성은 종종 다음을 포함하여 콘텐츠 스타일 가이드에 포함됩니다. Microsoft 와 Mailchimp.

당신은 개발자이고 아마도 이미 접근성에 대해 많이 알고 있을 것입니다. 접근성을 워크플로의 핵심 부분으로 만드는 더 부지런한 개발자 중 하나일 수도 있습니다. 모든 기능을 포함하는 액세스 가능한 온라인 경험을 만드는 것이 얼마나 중요한지 우리 모두가 알고 있음에도 불구하고 액세스 가능성 고려 사항이 얼마나 자주 백 버너에 놓이는지 놀랍습니다.

따라서 다른 사람의 카피라이팅을 코드에 구현하거나 다른 개발자를 위한 문서를 작성하거나 심지어 UI 기술 작성에 대한 다른 모든 조언을 마무리하는 몇 가지 기본적인 접근성 모범 사례를 염두에 두고 자신을 복사하십시오.

같은 것들:

Andy Bell은 상대적으로 콘텐츠의 접근성을 높이기 위해 할 수 있는 작은 일, 시간을 내어 확인해 볼 가치가 있습니다. 그리고, 단지 킥을 위해, John Rhea는 몇 가지 깔끔한 편집 트릭을 보여줍니다. 의미론적 HTML 요소로 작업할 때 가능합니다.

결론

기술적인 글쓰기와 개발이 어떻게 일치하는지 보여주는 XNUMX가지 방법이었습니다. 예제와 조언이 로켓 과학이 아닐 수도 있지만, 다른 개발자와 공동 작업을 하든, 자신의 작업을 유지 관리하든, 급하게 자신의 사본을 작성해야 하든, 프로젝트 제안 초안을 작성하든 간에 유용하게 사용하셨기를 바랍니다. 것들.

결론: 작문 기술을 연마하고 작문에 약간의 노력을 기울이면 실제로 더 나은 개발자가 될 수 있습니다.

테크니컬 라이팅 리소스

기술 문서 작성에 관심이 있는 경우:

카피라이팅에 관심이 있다면:

현미경에 관심이 있다면:

글쓰기를 향상시키기 위해 전문적인 스타일 가이드를 사용하는 데 관심이 있다면:

접근성을 위한 글쓰기에 관심이 있다면: