기술문서 작성법에 대해

[kgneng2]

• https://tech.kakaoenterprise.com/65

1. 기획

• 개발과 유사하게 문서작성도 기획 구조화 작성(개발) 리뷰 배포형식으로 진행한다.
• 팀원과 같이 진행하였으므로 리뷰와 배포를 진행하면 좋을꺼같은데.. 리뷰는 어떤방식으로 ??
• 문서 이해 관계자에 따라 이해를 다르게 해야한다.

2. 구조화

• 목차구성

3. 문서작성

• 작성진행
• 4대원칙 : 명확성, 간결성, 정확성, 일관성
• 프로젝트가 다 끝나고 작성하면 시간이 쫒긴다. 다른 프로젝트, 유지보수 등등..
• 고로 언제 작성을 해야할까???

4. 리뷰

• 초안작성자와, 팀원이 진행

• https://gist.github.com/9beach/41b8b51b13e4704653a8

문서작성시 유의점

1. 반드시 두괄식은 아니지만 도입부를 정의하고 시작하면 좋을것 같다.

   (O) 커버로스는 ... 컴퓨터 네트워크 인증 프로토콜이다.
   (X) 커버로스는 ... 보안을 위해 만들어졌다.

2. 배경 목적 범위를 도입부에 간략하게 작성하면 이해가 편할수 있다.

3. 외국 문자와 혼동은 피한다. 기술용어는 영어로 써야겠지만, 일반 단어를 영어화하지않는다.

   (O) 합의했다.
   (△) 합의를 이루었다.
   (△) 컨센서스를 이루었다.
   (X) Consensus를 이루었다.
   (O) 도쿄에서
   (X) 東京에서
   (△) 동경에서
   (O) 도쿄(東京)에서
   (O) 런던(London)에서
   (O) 런던에서
   (X) London에서

• https://macaronpark.github.io/sdd-1/

  IEEE Std 1016-1998 IEEE Recommended Practice for Software Design Descriptions Abstract: The necessary information content and recommendations for an organization for Software Design Descriptions (SDDs) are described. An SDD is a representation of a software system that is used as a medium for communicating software design information. This recommended practice is applicable to paper documents, automated databases, design description languages, or other means of description.

Keywords: software design, software design description, software life cycle process

1. 개요 1.1 문서의 목적 1.2 문서의 범위 1.3 소프트웨어 /프로젝트 기능요약

2. 데이터 설계 2.1 개체 관계도 2.2 테이블

3. 아키텍쳐 설계 3.1 데이터 흐름도