9beach 9beach

기술 문서를 쓸 때 주의해야 할 몇 가지

독자 배려

자신의 생각과 할 일을 정리하는 것이 기술 문서의 목표가 될 수는 없다. 먼저 독자를 식별하라. 그리고 독자를 배려하고 독자 입장을 생각하며 문서를 작성하라.

텍스트 파일의 장점

중요한 정보를 위키나 깃(Git)에서 텍스트로 작성하지 않고, 워드나 파워포인트 같은 이진 문서로 작성할 때마다 당신의 동료는 접근성, 가시성, 버전 관리 등 다양한 문제로 고생할 것이다.

먼 나라 바닷가로의 여행을 위한 준비물

필요한 것

여권
여권 사본 (오지에 가는 것이 아니라면 클라우드 서비스에 사진을 올리는 것으로 충분하다.)
항공권 (스마트폰이 있다면 클라우드 서비스에 사진을 올리는 것으로 충분하다.)
신용카드 (대부분의 국가에서 가장 유리한 지불 수단이다.)
도착지의 기후, 안전도, 풍토병 등에 대한 정보
론니 플래닛 (여행 관련 웹 서비스가 주지 못하는 소중한 정보는 여전히 존재한다.)
약간의 현지 돈 (ATM이 항상 주위에 있는 것은 아니다.)
킨들 또는 몇 권의 책

ATAM의 이해

소프트웨어 품질과 아키텍처의 연관성은 명확해 보인다. 특히 품질 속성 주도의 디자인^{Attribute-Driven Design}이 지배적인 방법론인 것을 고려하면 거의 동의어로 느껴질 정도이다. 이런 이유로 소프트웨어 품질 향상을 위해 아키텍처 평가 방법론을 살펴보는 것도 뜻이 있다고 생각한다. 이 글은 이런 배경에서 쓰였고 따라서 세부 절차보다는 평가 방법론의 주요 개념을 살펴보는 데 집중한다.

평가가 필요한 때

일을 끝낸 뒤에 그 결과와 과정을 평가하는 것도 뜻이 있지만 되돌리는 비용이 큰 결정에 앞서 그 결정의 적합성을 검토하고 평가하는 것도 뜻이 크다. 이런 평가가 효율적으로 이루어진다면 시행착오로 인한 비용을 줄이고 그 결정에 근거해서 수행될 일의 질 또한 높여 줄 것은 분명하다. 따라서 많은 선택과 결정이 전체 프로세스 상의 한 지점에서 이루어졌다면, 직후에 양식을 갖추어 평가를 시도하는 것은 고려할 가치가 있다. 오늘 소개하고자 하는 ATAM^{Architecture Tradeoff Analysis Method}은 소프트웨어 시스템 아키텍처의 장단점을 분석하는 방법론으로써 이런 평가의 취지에 부합한다.

ATAM 들여다보기

설치할 것

공통

First, install git.

macOS

Be sure to change hostname!

읽은 책

2015년 2월부터 읽은 책. 2019년 여름부터 2022년까지 병으로 읽지 못하고 2023년부터 다시 읽기 시작함.

특별히 꼽고 싶은 책, 재미있었던 순으로

Out of Africa - Karen Blixen
안나 카레니나 - 레프 톨스토이, 펭귄클래식
브로크백 마운틴 - 애니 프루
아들과 연인 - 데이비드 허버트 로런스, 열린책들

비주얼 스튜디오 코드 한스펠 설정

사용자 정의 표현식(~/.hanspell-bad-expressions.json)을 중심으로 “비주얼 스튜디오 코드 한스펠”의 설정 예시를 제공합니다.

사용자 정의 표현식

맞춤법 검사를 한 번이라도 실행한 문서라면 수정할 때마다 사용자 정의 표현식이 자동으로 적용됩니다.

아래의 저의 ~/.hanspell-bad-expressions.json 파일입니다. 김정선 작가의 《내 문장이 그렇게 이상한가요?》에서 많이 가져왔습니다.

	#!/usr/bin/env node

	/**
	* @fileOverview Converts Tygem's GIB format to SGF.
	*/

	// GIB format example.
	//
	// \HS
	// ...