본문 바로가기
Software Architect/SI 프로젝트 가이드

개발가이드 작성 및 개발자 교육

by romainefabula 2018. 3. 11.

개발자가 사용할 개발환경에 대한 준비가 끝나면 개발가이드를 작성해야 한다. 개발가이드는 프로젝트에 투입된 개발자들도 참조하지만 시스템을 오픈한 후에 유지보수를 담당하거나 그 후에 인력이 변경될 경우에 인계받은 개발자도 볼 수 있기 때문에 설명을 듣지 않더라도 문서만으로 필요한 내용을 찾을 수 있도록 정보를 빠짐없이 기록해야 한다. 어떤 종류의 가이드나 마찬가지겠지만, 글만으로 설명하는 것보단 그림을 그리거나 샘플코드를 보여 주면서 개발순서에 따라 하나씩 차례로 설명하는 것이 이해도를 높이는 데 도움이 된다.

소프트웨어 아키텍처

먼저 소프트웨어 아키텍처에 대한 설명을 한다. 소프트웨어 아키텍처 구성도와 함께 구성요소와 각각의 역할에 대해 간단히 설명한다. 구성요소가 많다면 처음에는 모두를 포함한 큰 구성도를 그리고, 밀접한 관련이 있는 시스템끼리 묶어서 상세하게 작성된 구성도를 차례로 그리고 설명해 나간다.
참고로, 소프트웨어 아키텍처 문서는 여기서 설명하는 개발가이드와 별도로 만드는 것이 좋다. 개발가이드는 개발자에게 필요한 내용만 담고, 소프트웨어 아키텍처 문서는 소프트웨어 아키텍처를 포함한 개발프레임워크의 모든 기능과 그에 대한 설정을 모두 담아서 SWA 자신을 포함해서 후임자나 운영담당자가 참고할 수 있도록 최대한 자세한 내용을 담도록 한다.

개발 프레임워크

다음으로 개발프레임워크에 대해 설명한다. 개발프레임워크에 대한 그림을 그리고, 각 레이어별 역할과 개발이나 수정을 해야 할 담당자(SWA, 개발자 등)를 표시해 개발자가 혼란없이 자신의 역할에 집중할 수 있도록 정리해 준다.

개발환경 설치

이제 개발환경 설치에 대해 설명한다. 기본적인 개발환경은 압축만 풀면 준비가 되니까 간단하지만, 그 안에 포함된 프로그램과 관계에 대한 설명은 해야 한다. 그리고, 압축파일에 포함시킬 수 없고 인스톨 프로그램을 통해서만 설치되는 프로그램에 대해서는 설치에 대한 설명을 추가한다.

코딩 표준

코딩을 할 때 지켜야 할 코딩 표준에 대해서 기술한다. 이 규칙은 정적분석 툴에도 적용해야 하므로, 혼동되지 않도록 명확한 내용으로 작성한다.

샘플코드 및 개발가이드

다음은 만들어 놓은 샘플 CRUD 프로그램을 보여 주며 어떤 파일을 어떤 패키지나 디렉토리에 생성해야 하며, 프로그램이나 설정 파일을 어떻게 작성해야 하는지 설명한다. 파일이나 패키지, 클래스, 메소드 등의 명명규칙은 설계자에게 전달되어 그대로 설계에 적용되었을 테니 설계문서대로 개발하면 되겠고, 개발가이드 문서에서는 명명가이드 문서에 대한 정보만 기술해 주면 된다.

테스트 프로그램 개발가이드

소스코드에 대한 테스트와 코드 커버리지를 확인할 수 있도록 JUnit 등의 테스트 프로그램을 작성하는 방법에 대해 설명한다. 코드 커버리지 통과 기준에 대해 미리 정하고 이것도 기술해 놓는 것이 좋다.

인터페이스 개발가이드

기본적인 개발프레임워크를 사용한 프로그램 외에 인터페이스 등 성격이 다른 프로그램을 개발할 필요가 있을 경우에는 하나씩 처음부터 끝까지 개발하는 과정을 차례로 설명하는 방식으로 작성한다.
인터페이스를 개발할 때 단순한 코드가 아니라 GUI 툴을 사용해야 할 경우, 툴을 사용하는 과정을 한 화면씩 캡처해서 상세하게 설명하는 것이 좋다. 잘 만든 가이드 하나는 몇십 몇백 개의 개발자 질문을 사라지게 한다.

형상관리 사용가이드

개발하기 전에 형상관리 시스템에서 기본소스를 내려받는 과정과 하나씩 개발을 완료했을 때 형상관리 시스템에 소스를 올리는 과정에 대해서도 설명한다.
프로젝트에서 사용할 형상관리 시스템이 개발자들에게 생소한 경우, 형상관리 시스템에 대한 간단한 설명도 하는 것이 좋다.

소스 빌드/배포 가이드

개발한 프로그램을 테스트하기 위해 소스를 빌드하고 서버에 배포하는 방법에 대해서도 기술한다. 빌드 및 배포는 보통 개발자 개인이 하지 않고 각 개발팀에서 담당자가 일정주기로 한꺼번에 하는 것이 좋으므로 이에 대해 미리 개발팀과 협의를 통해 수동으로 할지, 스케줄링을 통해 할지도 결정하는 것이 좋다. 개발자 교육을 실시하기 전에 형상관리 시스템에서 개발자별로 사용할 계정을 미리 받아서 생성해 두는 것이 좋다. 그래야 교육 중이나 교육 직후에 개발과정을 바로 따라해 볼 수 있기 때문이다.

개발자 교육

개발가이드를 작성했으면 개발단계가 시작되는 시점에 개발자 교육을 실시한다. 가장 좋은 환경은 개발자들이 설명을 들으면서 자신의 컴퓨터를 이용해 직접 개발을 따라해 보는 것이다. 백견이 불여일타라고, 역시 백번 보는 것보다 한번이라도 직접 키보드를 두드려 보고 결과를 확인해 보는 것이 오래 기억에 남는다. 이런 환경이 준비되지 않으면 어쩔 수 없이 내용을 보면서 설명을 해야 한다. 교육 중간이나 종료 후에 질문을 듣고 답변을 하는 시간도 필요하다. 개발자 교육 이후에 개발자들의 질문을 받고 그에 답변을 하며, 개발프레임워크나 공통모듈이 추가/변경되었을 때 이를 공지하는 목적으로 개발자 게시판을 만들어 운영하는 것이 좋다.
집합교육을 하기가 어렵거나, 소수의 개발자들이 수시로 들어와 교육하기가 힘들 경우에는 교육동영상을 만드는 방법도 있다. 경험상 가이드문서만 잘 만들면 교육이 필요없는 경우가 있었기 때문에, 가이드와 교육이 가장 중요하고 동영상은 보조수단 정도로 사용하는 것이 좋다.

 

 

1. 소프트웨어 아키텍트란?

2. 요구사항 조사

3. 소프트웨어 아키텍처 설계

4. 개발 프레임워크 설계

5. 로컬 개발환경 구성

6. 개발프레임워크 준비

7. 개발가이드 작성 및 개발자 교육

8. 개발단계에서의 개발자 지원

 

 

'Software Architect > SI 프로젝트 가이드' 카테고리의 다른 글

소프트웨어 아키텍처 설계  (0) 2022.03.21
요구사항 조사  (3) 2022.03.17
개발단계에서의 개발자 지원  (0) 2018.07.14
개발프레임워크 구현  (0) 2018.03.01
로컬 개발환경 구성  (0) 2018.02.16