소프트웨어 설계 문서 작성이 중요한 이유

축하합니다. 당신은 유능한 독립 개발자입니다. 테스터로 일할 수 있는 미약한 시작부터 팀 개발자, 그 다음에는 시니어 개발자로 발전했고 지금은 클라이언트와 직접 작업하는 데 가장 큰 도약을 했습니다.

그러나 다른 전환이 선형인 경우 마지막 전환은 기하급수적이었습니다. 과거에는 고객과 함께 일하거나 소프트웨어 비즈니스에 종사하는 고용주로부터 행진 명령을 받았지만 이제는 전문가 테스트, 프로그램 관리 등 사이에 한때 분산되었던 모든 책임이 모두 귀하의 것입니다. 그리고 지금 당신은 소프트웨어 사업에 종사하지 않는 고객들과 일하고 있습니다. 그들은 소프트웨어를 필요로 하는 다른 비즈니스에 있고 그들이 원하는 것에 대한 명확하고 정확한 비전이 없습니다. 이것은 보이는 것보다 훨씬 더 큰 도전입니다.

*참고:* 여기에서는 개발자로부터 1인 군대를 원하는 소규모 클라이언트에 대해 설명하고 있습니다. 프리랜서가 선택할 수 있는 유일한 경로는 아니며 Toptal에서 작업하는 유일한 고객은 아니지만 제가 가장 좋아하는 경로입니다. 물론 혼자가 아닌 팀으로 작업하는 경우 아래 중 일부는 적용되지 않습니다. 예를 들어 Agile 방법론이나 Scrum을 사용하는 경우 이정표를 약간 다르게 구성하고 싶을 것입니다.

의사 소통의 최고 중요성에 대해 모두 들어보셨을 것입니다. Skype를 통해 몇 문장의 간결한 설명을 듣고 "3개월 후에 일이 끝나면 만나요"라고 말하는 것으로는 일할 수 없습니다. 클라이언트와 통신해야 하며 작업의 모든 단계에서 목표에 대한 일치하는 아이디어가 있는지 확인해야 합니다. 클라이언트가 와이어프레임과 자세한 기능 사양을 보내는 경우는 실제로 드물기 때문입니다. 소프트웨어가 수행해야 하는 작업, 모양 및 흐름에 대한 매우 일반적인 아이디어를 얻을 수 있습니다. 일반적으로 시작하는 피상적인 설명을 기반으로 애플리케이션을 작성하면 클라이언트가 결과에 만족할 가능성이 거의 없습니다. 각 단계에서 합의에 가까워지는 과정을 반복해야 합니다.

팀의 모든 구성원이 같은 문화권 출신이고 같은 모국어를 사용하고 같은 복도에서 일하고 매일 서로 만나는 등 소프트웨어 비즈니스에 종사하는 회사에서 수년간 근무한 것은 주목할 만합니다. 회사는 여전히 절반의 시간 동안 원하는 것을 얻지 못했습니다. 실수하지 마십시오. 여기서의 도전은 엄청납니다.

소프트웨어 설계 문서가 중요한 이유

따라서 새 프로젝트를 맡을 때 Xcode나 Visual Studio를 열기도 전에 명확하고 합의된 디자인 목표가 있어야 합니다 . 그리고 이러한 목표는 사양 문서에 설정되어야 합니다. 클라이언트가 작성하지 않은 경우 작성하고 IDE를 열기 전에 검토를 위해 제출해야 합니다. 그리고 "설계 문서를 작성할 시간이 없다"고 말하는 클라이언트를 만나면 솔직히 앞으로 문제가 있기 때문에 프로젝트를 떠나야 합니다 . 사양이 특별히 길 필요는 없습니다. 몇 페이지에 불과할 수 있지만 최소한 사용자 인터페이스를 배치하고 와이어프레임(UI 구성요소가 있는 경우)을 포함하고 완료 이정표를 설정해야 합니다.

이 문서가 없으면 고객은 신랄한 애매모호함의 루프에 빠지게 됩니다. 고객은 고객이 말한 내용 또는 고객이 말한 내용에 대해 이의를 제기하고 화를 내며 이전 통신 내용을 잘라내어 붙여넣고 고객이 요구할 때까지 해석하고 논쟁하게 됩니다. 응용 프로그램이 "실제로 요청한 것"과 일치하도록 변경하고 비용을 지불하지 않고 변경하기를 기대합니다.

이 소프트웨어 설계 문서를 사용 하면 그러한 문제에 대한 답을 얻을 수 있습니다. 불일치가 발생하면 클라이언트가 동의하고 서명한 사양을 참조하여 서신에 그것을 이행했음을 지적할 수 있습니다. 화난 주장 대신 문서를 수정하고 설명합니다. 무엇이든 고객은 처음부터 부정확성을 통과한 것에 대해 사과할 것입니다.

우리 모두는 만족스러운 고객을 원합니다. 우리 모두는 우호적인 업무 관계를 원합니다. 그리고 우리 모두는 일을 잘했다는 자부심을 원합니다. 그러나 직업이 실제로 무엇 인지 에 대해 모호한 점이 있으면 달성할 수 없습니다. 클라이언트가 설계 문서가 너무 많은 추가 작업이라고 말하면 일종의 오해로 인해 수정해야 할 때 실제 추가 작업이 나타날 것이라고 설명하는 것이 귀하의 일입니다. 클라이언트 가 여전히 그러한 문서 없이 진행하라고 주장한다면, 당신은 당신이 일할 수 없는 관계라는 사실을 받아들이고 떠나야 합니다.

소프트웨어 설계 사양은 실제로 무엇을 지정해야 합니까?

최소한 원하는 지원서, 완료 기준 및 이정표에 대한 설명이어야 합니다. 구현 사양이 아니라 요구 사항 및 기능 문서로 가장 잘 설명된 내용을 공유하고 있음을 기억하십시오. 그리고 특정 구현이 명시된 클라이언트 목표가 아닌 한 구현 방법은 사용자에게 달려 있습니다.

사용자 인터페이스

대부분의 프로젝트는 라이브러리나 프레임워크가 아닌 애플리케이션입니다. 그러나 이 중 하나를 결과물로 가지고 있다면 사용자 인터페이스가 디자인 문서 템플릿의 가장 문제가 되는 구성 요소 이고 거의 항상 오해를 불러일으키기 때문에 운이 좋다고 생각하십시오. 많은 클라이언트가 프로그래머가 아닌 그래픽 디자이너가 그래픽 편집기에서 만든 완벽한 일러스트레이션을 보내드립니다. 그러나 문제는 이 그림이 애니메이션, 제어 상태(예: 이 버튼이 비활성화되어 있습니까? 사용할 수 없을 때 사라지나요?) 또는 버튼을 눌렀을 때 수행할 작업에 대해 아무 것도 말하지 않는다는 것입니다.

이 그림 뒤에 있는 코드를 작성하기 전에 이러한 모든 질문에 답할 수 있어야 합니다. 구체적으로 다음 사항을 알아야 합니다.

1. 컨트롤이 항상 표시 및/또는 활성화되어 있습니까? 그들의 상태는 어떤 조건에서 변경됩니까?
2. 비트맵처럼 보입니다. 버튼인가요?
3. 이러한 상태와 보기 간에 어떤 전환이 발생합니까? 어떻게 애니메이션화해야 합니까?

클라이언트의 동시성을 위해 UI를 생성하는 것이 당신에게 달려 있다면, 역으로 동일하게 수행하십시오. 와이어프레임 도구를 사용하고 보기가 다른 애플리케이션 상태에서 표시하는 변형을 포함하여 완전한 화면 레이아웃 세트를 생성하십시오. 이것은 철저하고 지루한 작업일 수 있지만 후회하지 않을 것입니다. 큰 의미의 사소한 오해로 인해 막대한 양의 코드를 다시 작성하고 인터페이스를 다시 만드는 일을 피할 수 있습니다. 이중 응용 프로그램(예: iPhone 및 iPad용)을 생성하는 경우 둘 다에 대해 별도의 와이어프레임을 생성합니다.

화면 크기도 중요합니다. (글을 쓰는 현재) 아이폰 화면은 3가지 크기가 있습니다. 3.5" 및 4" 화면에 대한 별도의 와이어프레임은 아마도 과도할 수 있지만 만들어야 할 수도 있습니다. 대부분의 경우 단순히 비율을 변경할 수 있습니다.

클라이언트가 그래픽을 제공하는 경우 적절한 가로 세로 비율로 크기가 올바른지 확인하십시오. 텍스트나 개체(예: 원)가 있는 비트맵을 변형하면 왜곡이 발생합니다. 일치하지 않으면 클라이언트에게 일치하는 크기로 다시 만들도록 지시합니다. 3.5인치 스플래시 화면을 4인치 스플래쉬로 늘릴 수 있다고 생각하지 말고 그냥 굴려보세요.

기능

응용 프로그램 설계 문서에서 묻는 주요 질문:

• 응용 프로그램은 무엇을 하며 얼마나 빨리 수행합니까?
• 가능한 고장 조건은 무엇이며 어떻게 처리합니까?
• 첫 번째 실행 시(즉, 설치 후) 어떤 일회성 작업이 수행됩니까?
• 사용자가 모든 종류의 항목(예: 책갈피)을 만드는 경우 제한 사항은 무엇입니까?

이러한 아이디어를 일반화하고 최대한 상세하고 철저하게 작성하십시오. 여기서 오류나 오해는 코드를 다시 작성하는 것을 의미하기 때문입니다.

이정표

사양 템플릿은 명확한 이정표를 배치해야 합니다. 클라이언트가 기능 및 사용자 인터페이스 디자인을 작성하는 경우 이후에 일련의 이정표에 동의해야 합니다. 때때로 이는 청구 임계값이기도 하지만 최소한 완료에 대한 명확한 지표를 제공합니다. 이정표는 기능 및/또는 구성 요소와 관련이 있을 수 있습니다. 공연에 일련의 결과물이 포함되는 경우 별도의 응용 프로그램이 될 수도 있습니다. 가능한 경우 이정표는 기간이 거의 동일해야 합니다.

소프트웨어 설계 사양 예

여기에서는 적절한 설계 문서의 예제 구조를 배치하겠습니다. 물론 이 템플릿은 필요에 따라 조정해야 합니다. 다른 예는 이 글을 기반으로 한 Joel Spolsky의 샘플 사양을 참조하세요. 그는 문서에 약간 다르게 접근하지만 비슷한 감정을 공유합니다.

목표 선언문

프로젝트와 대상 청중을 설명하는 짧은 단락을 포함하십시오.

기능 설명

응용 프로그램은 무엇 을합니까 ? 사용자는 어떤 애플리케이션 상태(핵심 사용자 시나리오에 대한 상위 수준 설명)를 접하게 됩니까?

예를 들어 기능 설명은 다음과 같을 수 있습니다.

• 첫 실행
• 새로운 _____ 만들기(게임, 검색 등)
• 운영
• 배경 및 전경 동작

사용자 인터페이스

다음에 대한 자세한 설명과 함께 각 페이지에 대한 와이어프레임을 포함합니다.

• 상태(활성화/비활성화/강조 표시) 및 작업을 포함한 각 컨트롤.
• 지원되는 방향 및 전환.
• 기능이 표시됩니다.
• 오류 처리.
• 치수 및 구속조건.

다음은 제 최신 iOS 앱인 NotifEye와 관련된 와이어프레임입니다.

관심이 있으시면 Balsamiq의 와이어프레임 도구를 사용하여 이 모형을 만들었습니다.

예를 들어 UI 설명은 다음과 같을 수 있습니다.

• 탐색 모음
  • 왼쪽 탐색 컨트롤: 홈 페이지로 돌아가기
  • 제목 표시줄: 현재 화면 또는 작업 이름
  • 새 버튼: 새 사물 만들기
• 테이블 보기
  • 섹션 0: 섹션 제목
  • 섹션 0 행:
    • 행 제어 0(예: 이미지)
    • 텍스트 줄 0
    • 텍스트 라인 2

이정표

위에서 설명한 대로 완료 기한 및 예상 결과물.

예를 들어 디자인 문서 템플릿의 이정표 섹션은 다음과 같습니다.

1. 화면 및 임시 전환 및 예제 이미지/텍스트를 표시하는 Facade 애플리케이션
2. 통신 프로토콜: 애플리케이션이 네트워크/서버에 연결
3. 기능적 이정표 1: …
4. 알파 애플리케이션(전체 기능 포함)
5. 안정
6. 풀어 주다

소프트웨어 문서가 관련성을 유지하는지 확인

귀하와 귀하의 클라이언트가 사양 문서에 동의하면 설계 단계가 끝났다는 의미가 아닙니다. 당신 중 누구도 고려하지 않은 세부 사항이 항상있을 것이며 중간 결과를 보는 동안 당신과 클라이언트 모두 새로운 아이디어, 디자인 변경, 예기치 않은 디자인 결함 및 실행 불가능한 제안에 직면하게 될 것입니다.

디자인이 발전하고 변경 사항을 문서에 캡처해야 합니다. 제 25년의 경험에서 저는 이런 일이 발생하지 않은 프로젝트에서 일한 적이 없습니다. 여기에는 제 자신의 응용 프로그램이 포함됩니다(즉, 제가 제 고객이었던 곳). 그때도 세부 사양으로 디자인 문서를 작성하고 필요에 따라 조정했습니다.

무엇보다 연락을 유지하십시오. 적어도 일주일에 여러 번 고객에게 연락하여 진행 상황을 보고하고 설명을 요청하고 동일한 비전을 공유하는지 확인하십시오. 당신의 의사소통을 위한 리트머스 테스트로서 당신과 당신의 고객이 다음 세 가지 질문에 대해 같은 대답을 하는지 확인하십시오.

1. 개발자가 방금 작업한 것은 무엇입니까?
2. 개발자는 현재 어떤 작업을 하고 있나요?
3. 개발자는 다음에 무엇을 할 것인가?