개요
블로그 글을 열심히 쓰다보니, 어떻게 하면 글을 사람들에게 쉽게 전달하고 가독성이 좋게 만들 수 있을까 고민합니다. 그러다 개발자를 위한 글쓰기 책이 있다고 하여 구매하여 읽게 되었습니다.
'테크니컬 라이팅 45가지 원칙' 중에 도움이 될만한 내용을 추려보겠습니다.
08 핵심부터 쓴다
텐서플로(TensorFlow)는 구글 브레인(Google Brain)팀에서 근무하는 연구자와 엔지니어가 기계 학습과 심층 신경망 연구용으로 개발했지만, 기타 분야에도 광범위하게 적용할 수 있는 범용성을 갖춘 시스템입니다. 텐서플로는 데이터 흐름 그래프를 사용하는 수치 연산용 오픈소스 소프트웨어 라이브러리입니다. 유연한 아키텍처를 채택하여 단일 API를 통해 데스크톱, 서버 또는 휴대기기에 장착된 하나 이상의 CPU 또는 GPU 연산을 배포할 수 있습니다
-> (핵심 문장을 맨 앞에 표현 할 것)
텐서플로(TensorFlow)는 데이터 흐름 그래프를 사용하는 수치 연산용 오픈소스 소프트웨어 라이브러리입니다. 구글 브레인(Google Brain)팀에서 기계 학습과 심층 신경망 연구용으로 개발했지만, 다른 분야에도 광범위하게 적용할 수 있습니다. 아키텍처가 유연하여 API 하나로 데스크톱, 서버, 휴대 기기에 장착된 여러 CPU나 GPU에 연산을 배포할 수 있습니다.
13 용어와 약어를 쓸 때는 풀이를 쓴다
스니퍼는 스니핑을 할 수 있는 도구를 말합니다.
(스니퍼가 어떤 뜻인지 간단하게 설명을 한다.)
스니핑(sniffing)을 할 수 있는 도구를 스니퍼(sniffer)라고 한다. 스니핑은 해킹 기법의 하나로, 네트워크에서 상대방의 패킷 교환을 엿듣는 것을 의미한다. 이렇게 스니핑을 할 수 있는 도구를 스니퍼라 한다.
또한 약어는 맨 처음에 풀어서 써야 하며, 용어집을 만드는 것도 하나의 방법입니다.
24 맥락에 맞는 적확한 단어를 선택한다
KM 클라우드 푸시 서비스를 사용하면 쉽게 푸시 발송을 보낼 수 있습니다.
-> KM 클라우드 푸시 서비스를 사용하면 푸시 알림을 보낼 수 있습니다.
지난 서비스보다 성능이 훨씬 개발되었습니다.
-> 지난 서비스보다 성능이 훨씬 향상되었습니다.
크기 및 전기 소모가 작습니다
-> 크기가 작고 전기 소모가 적습니다.
25 은어는 형식적인 표현으로 바꾼다
로그를 까 보고 설정을 다르게 줘 보는 것부터 해 보죠.
-> 로그를 확인해 설정을 바꾸는 것부터 해 보죠.
지금은 프로그램이 너무 무거운 것부터 개선하면 좋겠습니다.
-> 지금은 프로그램 실행 속도가 매우 느린 것부터 개선하면 좋겠습니다.
이벤트에 로직을 태워 알림 창을 띄웠습니다.
-> 이벤트에 로직을 적용해 알림 창이 나타나게 했습니다.
에러를 잡았습니다.
-> 오류를 수정했습니다.
정보 입력 대화 상자가 뜨면 메일 주소와 휴대폰 번호를 입력합니다.
-> 정보 입력 대화 상자가 나타나면 메일 주소와 휴대폰 번호를 입력합니다.
일부 편집기에서 한글이 깨져 보일 수 있습니다.
-> 일부 편집기에서 한글이 제대로 보이지 않을 수 있습니다.
엑박이 뜹니다.
-> 그림이 제대로 보이지 않습니다.
26 대명사는 일반 명사로 바꾼다.
업무 캘린더를 사용하면 동료와 일정을 쉽게 공유할 수 있습니다.
또한 이를 통해 프로젝트 진척도도 관리 할 수 있습니다.
-> 업무 캘린더를 사용하면 동료와 쉽게 일정을 공유할 수 있습니다.
업무 캘린더에서 프로젝트 진척도도 관리 할 수 있습니다.
좀 더 많은 API 사용법을 보려면 여기를 참고하시기 바랍니다.
-> 좀 더 많은 API 사용법을 보려면 API 레퍼런스를 참고하시기 바랍니다.
27 고유한 이름은 정확히 쓴다.
모바일 운영체제로는 대표적으로 AOS와 IOS가 있다.
Android는 기기의 운영체제(OS)를 지칭하는 용어로만 사용되어야 합니다.
구글에서 trandemark list와 같이 검색하면 원하는 상표 표기 페이지를 쉽게 찾을 수 있습니다.
30 글꼬리를 뚜렷하게 쓴다
앞에서 설명한 문제 해결 방법이 유일한 방법이라고 말할 수는 없지 않을까 싶다.
-> 앞에서 설명한 문제 해결 방법이 유일한 것은 아니다.
KM 보안 서비스 도입으로 문제가 해결 될 것이라 판단되는 바이다.
-> KM 보안 서비스 도입으로 문제가 해결 될 것이다.
KM 클라우드 도입 이유를 다음과 같이 크게 세 자기로 갈라 볼 수 있다.
-> KM 클라우드를 도입해야 하는 이유는 크게 세 가지다.
33 군더더기 표현을 없앤다
인증서 도에민당 월 8만 원의 비용이 발생합니다.
-> 인증서 비용은 도메인당 8만 원입니다.
서비스 활성화를 진행하기 위해서는 먼저 콘솔 로그인이 필요합니다.
-> 서비스를 활성화하려면 먼저 콘솔에 로그인해야 합니다.
원하는 파일 유형을 선택해 다운로드 진행해 주세요
-> 원하는 파일 유형을 선택해 다운로드해 주세요.
사용자 ID 설정 처리 이후에 초기화를 진행하십시오
-> 사용자 ID를 설정한 후 초기화하십시오.
34 의미가 같은 표현은 한 번만 쓴다
조사 결과 과반수 이상이 새로 나온 메시저 앱이 이전보다 편리하다고 대답했다.
-> 조사 결과 과반수가... (혹은) 조사 결과 절반 이상이 ...
기존에 이미 저장한 데이터입니다.
-> 기존에 저장한 데이터입니다. (혹은) 이미 저장한 데이터입니다.
결제 수단 등록 시, 카드 정보를 입력하게 되면,
비밀번호를 만들기 위한 질문에 답변을 하게 되면 비밀번호가 생성이 됩니다.
->결제 수단을 등록할 때, 비밀번호를 만들려면 카드 정보를 입력하고
비밀번호 만들기용 질문에 답변해야 합니다.
이전 버전의 오류를 고치고 부족한 점을 보충해, 좀 더 개선하고 보완된 새 버전을 소개한다.
-> 버전 1.0의 오류를 고치고 기능을 보완한 버전 2.0을 소개한다.
35 피동태보다 능동태로 쓴다
Python은 귀도 반 로섬(Guido van Rossum)에 의해 개발되었습니다.
-> Python은 귀도 반 로섬(Guido van Rossum)이 개발했습니다.
결과 로그가 화면에 보여집니다.
-> 결과 로그가 화면에 나타납니다.
화면 오른쪽 상단에 보여지는 로그인 버튼을 클릭합니다.
-> 화면 오른쪽 위의 로그인 버턴을 클릭합니다.
이미지가 반복되어져서 화면에 나옵니다.
-> 이미지가 반복해 화면에 나타납니다.
아이템 목록에 담겨진 항목입니다.
-> 아이템 목록에 있는 항목입니다.
선택한 파일의 데이터가 읽혀지면 '출력 모드'로 화면이 전환된다.
->선택한 파일의 데이터를 읽으면 '출력 모드'로 전환된다.
36 복잡한 번역체를 다듬는다
자바 스크립트 성능에 대해 알아보자
-> 자바 스크립트 성능을 알아보자
성능을 향상시키는 것은 코드 스타일을 다듬는 것에 의해 이뤄질 수 있다.
-> 코드 스타일을 다듬어 성능을 향상 할 수 있다.
성능 향상은 다음 3가지 방법을 통해 가능하다.
-> 성능 향상은 다음 3가지 방법으로 가능하다.
-> 성능은 다음 3가지 방법으로 향상할 수 있다.
-> 성능 향상 방법은 다음 3가지이다.
원하는 기능을 선택해 적용할 수 있어 자유도가 높습니다.
원하는 기능을 자유롭게 선택할 수 있습니다.
모바일 기기들은 기종별로 다양한 해상도를 가지고 있습니다.
->모바일 기기의 해상도는 기종별로 다릅니다.
관리 페이지 호출의 경우 다음과 같은 순서로 관리 페이지가 표시됩니다.
-> 관리 페이지를 호출하면 다음고 같은 수서로 관리 페이지가 표시됩니다.
37 '통해'는 명확한 표현으로 바꾼다
이번 테스트에서 나타난 문제점 파악을 통해 부족한 기능을 보완하면 판매가 늘 것이다.
-> 이번 테스트에서 나타난 문제점을 파악해 부족한 기능을 보완하면 판매가 늘 것이다.
콘솔을 통해 예약 알림을 설정할 수 있고 API 호출을 통해서도 알림을 보낼 수 있습니다.
-> 콘솔을 통해 예약알림을 설정할 수 있고 API를 호출해 알림을 보낼 수도 있습니다.
네트워크를 통해 전송합니다.
-> 네트워크로 전송합니다.
빌드 버튼을 통해 빌드를 생성합니다.
-> 빌드버튼을 클릭해 빌드를 생성합니다.
39 '~해 주다' 대신 '~ 하다'를 쓴다
Google 계정으로 로그인을 사용하려면 다음과 같이 구현해 주어야 합니다.
-> Google 계정으로 로그인을 사용하려면 다음과 같이 구현해야 합니다.
자주 사용하는 메뉴는 홈 화면으로 추가해 놓아 두고 사용하시면 됩니다.
-> 자주 사용하는 메뉴는 홈 화면으로 추가해 사용하면 편리합니다.
40 조사를 덜어낸다
시스템 사용을 하기 전에 환경부터 설정을 해야 합니다.
-> 시스템을 사용하기 전에 환경부터 설정해야 합니다.
데이터가 많아 클라우드 서비스로의 이전이 어렵다면
-> 데이터가 많아 클라우드 서비스로 이전하기 어렵다면
환경 설정의 편리함
-> 편리한 환경 설정
사용자들과의 의견의 교환으로 프로그램의 개선을 이룰 수 있었다.
->사용자들과 의견을 교환해 프로그램을 개선할 수 있었다.
45 자주 틀리는 문장 부호
12월 26일 출시 예정입니다
->12월 26일 출시 예정입니다.
2020. 12. 26
-> 2020. 12. 26.
개발자를 위한 테크니컬 라이팅 가이드 : 50가지 팁
-> 개발자를 위한 테크니컬 라이팅 가이드: 50가지 팁
2시부터 6시까지
-> 2시~6시
53 오류 메세지에서 중요한 것은 해결 방법
오류메세지의 3요소 : 원인, 상태, 해결 방법
상태 : 저장공간이 부족하여
원인 : 파일을 업로드 하지 못했습니다
해결 방법 : 사용하지 않는 파일을 삭제하고 다시 시도해 주세요.
54 메세지에서도 제목을 활용한다
직관적인 제목으로 표현하기
55 직관적인 버튼 텍스트를 만든다
느낀 점
개발IT 서적보다는, 글쓰기 서적 같았습니다. 대상 독자와 글의 수준을 정하는 것부터, 어떻게 글을 써야하는지, 어떤 용어는 피해야 하는지까지 친절하게 예시를 통해서 알려줍니다. 이전에 가지고 있던 잘못된 습관을 돌아보는 계기가 되었습니다. 특히, "~를 통해", "피동태 형태", 진행, 필요 등의 "군더더기 표현", "번역체 해석" 등을 반성했습니다. 말을 길게 늘여뜨리면 뭔가 있어보이는 착시효과(?)로 즐겨쓰곤 했는데 교정의 필요성을 느꼈습니다. 단순히 IT 글 작성할 때뿐만이 아니라, 어떠한 글을 쓰든지 짧고 굵게 요약해서 볼 수 있어서 좋았습니다.
반응형
'회고 > IT도서' 카테고리의 다른 글
| 개발자 원칙 (0) | 2023.02.07 |
|---|---|
| 개발자의 글쓰기 (0) | 2022.10.22 |
| UML 실전에서는 이것만 쓴다 (0) | 2022.09.20 |
| The Nature of Software Development (0) | 2022.09.15 |
| 함께 자라기 (1) | 2022.09.09 |
