제품 설계 결정의 근거를 효과적으로 기록하는 방법은 무엇입니까?

우리 회사에서는 제품 디자인 문서를 사용하지 않습니다. 총 3 명의 직원이 있으므로 모든 제품 디자인 토론은 직접 또는 슬랙에서 이루어집니다. 또한 최신 메시지 만 볼 수있는 기본 Slack 패키지도 있습니다.

우리 제품은 아직 초기 단계에 있으며 종종 몇 달 전에 결정된 디자인 요소를 다시 방문합니다.

고민하면서 빈번하게 직면하는 문제는 제품 설계 결정이 내려진 이유를 잊어 버리는 것입니다. 그 결과 같은 시간에 여러 시간이 낭비되었습니다.

디자인 결정의 근거를 어떻게 효과적으로 기록 할 수 있습니까?

우리의 작업 흐름은 Pivotal Tracker를 기반으로합니다. 나에게 발생하는 한 가지 해결책은 모든 관련 디자인 결정에 대한 근거를 사용자 스토리 자체에 대한 의견으로 기록하는 것이지만 이것은 신뢰할 수없는 것 같습니다.

100 % 명확하게 : 코드 디자인에 대해 이야기하고 있지 않습니다. 코드로 실현되는 제품 디자인에 대해 이야기하고 있습니다. 다시 말해, 나는 "여러 상속이 아닌 컴포지션을 사용하여이 클래스를 구성해야합니까?"와 같은 결정에 대해서는 이야기하지 않습니다. "로그인하기 전에 사용자가 이메일 주소를 확인해야합니까?"와 같은 결정에 대해 이야기하고 있습니다.

문서의 목적은 비즈니스가 의사 결정이 이루어진 이유에 대한 기록을보고 동일한 주제에 대한 추가 결정을 내리는 데 도움을주기위한 것입니다.

설계 결정의 근거를 적어 기록합니다. 이상적으로 결정의 대상이되는 항목 ( "사용자 스토리"가 아님-사용자 스토리는 구현 방법이 아니라 구현해야하는 설명입니다.)

특정 주석 이나 구조가 왜 그렇게 보이는지 기록하기 위해 주석을 작성 하는 것이 특히 중요합니다 (코드 주석에 대해서만 이야기하고 있지는 않습니다). 디자인의 주제가 함수 인 경우 함수에 대한 소개 주석을 작성하십시오. 수업 인 경우 수업 시작시 이론적 근거에 대해 의견을 말하십시오. 모두 같은 구조를 따라야하는 클래스가 여러 개있는 경우 해당 클래스를 포함하는 패키지에 별도의 디자인 문서 (예 : "readme"파일)를 추가하십시오. 설계 주제가 UML 다이어그램 인 경우 다이어그램의 설명 섹션에 주석을 추가하십시오.

IMHO 디자인 문서는 그 가치가있을 수 있지만 설명하는 항목과 너무 멀리 떨어져있는 것을 묘사하면 매우 빨리 일관성이없는 경향이 있습니다. 따라서 권장 사항은 디자인 문서를 가능한 한 디자인 된 항목에 가깝게 두는 것입니다.

코드의 여러 위치에 영향을 미치는 설계 결정을 교차 절단 방식으로 문서화하려는 경우에만 별도의 문서를 사용하십시오. 그것들을 사용할 때, 그것들을 코드베이스의 일부로 만들어서 디자인 된 주제의 해당 계층 레벨에 배치하십시오 (따라서 많은 소스 코드 파일로 구성된 하나의 모듈에 대한 디자인 결정을 내리는 경우 디자인 설명을 배치하십시오 " 다른 모듈에 유효하고 SCCS 외부의 별도 Wiki에는없는 "최상위 설명"이 아닌 하나의 클래스 파일이 아닌 해당 모듈 내부에 " 광범위한 디자인 결정, 최상위 문서가 가장 적합한 장소 일 수 있지만이 문서가 해당 추상화 수준에 머물러 있는지 확인하십시오.

민첩한 접근 방식을 고려하십시오. 내 말은, 당신이 그들의 이론적 근거와 함께 모든 디자인 결정을 적을 시간 자원과 우수한 작문 기술이 있다면, 모든 것을 문서화하십시오. 사실, 나는 당신이 그런 입장에 있지 않다고 가정합니다. 민첩한 접근 방식은 이론적 근거를 문서화하는 데있어 주요 과제를 해결하는 데 도움이 될 수 있습니다. 나중에 어떤 이론적 근거가 중요한 것인지 잘 모릅니다.

전체적인 관점에서 문제에 접근합시다. 너희들은 당신의 결정에 대한 근거를 가지고 있습니다. 그들은 지금 팀의 두뇌 인 스 퀴시웨어에 갇혀 있습니다. 신용 문서의 양이 많음에도 불구하고 sqishyware에 근거를 저장하는 것이 그렇게 나쁘지는 않습니다. 우리는 실제로 중요한 것들을 기억하는 한 종으로서 정말 좋습니다. 그렇기 때문에 모든 주요 기업이 "부족 지식"을 갖고있는 이유는, 그러한 기업이 모든 부족 지식을 문서화하려고 할 때에도 마찬가지입니다.

이제 문제가 있습니다. 당신은 sqiushyware가 이론적 근거를 충분히지지하고 있지 않다는 것을 알게되었습니다. 문제가 있음을 인식하고 해결해야 함을 식별하는 데 도움이됩니다. 항상 쉬운 단계는 아닙니다! 따라서 우리는 해결책이 그 근거 중 일부를 문서로 오프로드하는 것이 확실합니다. 그러나 충분하지 않습니다. 우리는 퍼즐의 후반부를 결코 잊을 수 없습니다.이 결정은 결정을 내릴 때 squishyware에 이론적 근거를 다시로드합니다. 나는 미친 듯이하는 문서 모든 팀을 많이 본 적이 있지만 그들이 근거 잊고 끝낼 수 있도록 콘텐츠는 실제로 도움 메이크업 좋은 의사 결정에 구성되지 않은 그들이 써있는에도 불구을 .

따라서 2 단계 프로세스가 있습니다. squishyware와 문서에 대한 근거를 가져와야합니다. 그런 다음 필요한 경우 합리성을 다시 squishyware로 가져올 수 있도록 문서를 충분히 구성해야합니다! 이제 우리는 문제가 어디에서 일어날지를 깨닫기에 충분한 문제 진술을 가지고 있다고 생각합니다. 문서를 작성할 때 일반적으로 나중에 누가 볼 것인지 또는 무엇을 찾고 있는지 알 수 없습니다. 마찬가지로, 문서를 되돌아 볼 때 일반적으로 찾고있는 것을 알지 못합니다 (최대한 아는 경우).

따라서 대기업은이를 두 개의 큰 블록으로 처리하려고 할 수 있습니다. 먼저 사람들은 문서를 조사 할 때 사람들이 필요로하는 것을 기반으로 요구 사항을 개발할 수 있습니다. 그런 다음 해당 요구 사항을 사용하여 해당 문서를 개발하는 프로세스를 구축합니다. 그리고 내가 감히 말하면, 아무도 문서가 첫날에 어떤 모습 인지 정확히 알지 못하기 때문에 모두가 불평 합니다. 문서는 항상 불완전하며 개발자는 항상 프로세스가 너무 부담 스럽다고 불평합니다.

민첩하게 갈 시간.

저의 조언은 문서화 프로세스를 개선하기위한 민첩한 노력을 시작하는 것입니다 : 퀴질웨어에서 문서, 퀴질웨어까지 9 야드. 프로세스가 완벽하지 않기 때문에 일부 정보를 잃을 것이라는 점을 미리 인식하십시오. 그러나 프로세스를 파악하려고 시도해도 괜찮습니다! 모든 솔루션에 맞는 단일 크기를 만들려고하면 더 많은 것을 놓칠 수 있습니다.

내가 살펴볼 몇 가지 유용한 정보 : * 비공식 문서를 탐색하십시오. 공식적인 문서는 훌륭하지만 시간이 많이 걸립니다. 문서화의 목적 중 하나는 개발자 squishyware에서 정보를 공개하여 종이에 넣는 것입니다. 비공식 문서화는 최소한의 비용을 유지합니다.

• 신뢰할 수없는 문서 형식을 수락하십시오. 처음에는 옳지 않을 것입니다. 데이터를 가져 와서 나중에 신뢰할 수있게 만드는 방법을 알아내는 것이 좋습니다. 예를 들어, 근거를 <rationale> </ rationale> 블록 또는 이와 유사한 형식으로 문서화하면 나중에 해당 데이터를 쉽게 수집 할 수 있습니다. 사용자 스토리에 근거를 저장하는 것은 현재로서는 괜찮습니다!
• 조직의 가치를 잊지 마십시오. 팀원으로서 문서에서 이론적 근거를 검색하는 방법을 알아보고 문서화를 시도하십시오. 각 팀마다 다른 프로세스가 있습니다. 우리 팀 중 하나에서, 우리는 근거가있는 티켓을 즉시 찾을 수 없었습니다. 우리가 할 수있는 일은 중요한 코드 줄 svn blame을 찾아서 변경 시점과 이유 를 확인한 다음 티켓을 살펴보십시오. 일단 우리가 거기에 왔을 때, 우리는 일반적으로 우리가 필요한 모든 이론적 근거를 티켓에 올렸습니다. 그것은 우리를 위해 일했습니다, 당신에게 어떤 것이 효과가 있는지 알아보십시오.
• 유기적 문서는 시간이 지남에 따라 커질 수 있습니다. 개발자가 작성하는 데 가장 중요한 근거가 무엇인지 아는 것은 드문 일입니다. 우리는 보통 어느 것이 나중에 중요했는지 알아냅니다. 개발자가 자신의 작은 근거 정원을 관리 할 수 ​​있도록 문서화에 대한 정리 프로세스를 가지고 있다면 중요한 것들이 표면에 올 것입니다. 더 중요한 것은 근거가 바뀔 수 있다는 점입니다. 두 가지 다른 이론적 근거가있는 두 가지 다른 변경 사항이 두 가지 모두에 적합한 단일 이론적 근거에 의해 가장 잘 설명되었다는 것을 알고있을 것입니다. 이제 당신과 결정 사이에 내용이 적습니다!

MediaWiki 또는 유사한 위키 소프트웨어의 개인 인스턴스를 설정하는 것이 좋습니다. 컨텐츠를 구성하고 재구성하는 것이 매우 쉽고, 새로운 토론을 복사하여 관련 위키 기사의 토론 탭에 직접 붙여 넣을 수 있습니다. 우리는 마지막 아키텍처에서 모든 아키텍처 및 API 문서에 MediaWiki를 사용했으며 이는 생명의 은인이었습니다.

12 개월 안에 코드를 변경하라는 코더의 관점에서 생각하십시오.

이 비즈니스 규칙을 자동화 된 테스트로 추가하면 변경이 이루어지고 실패한 테스트에서 모순 된 요구 사항을 얻게됩니다 (원래 요구 사항과 연관된 사람과이를 지정한 이유를 파악하기를 바랍니다).

디자인 문서 (BPMN 다이어그램, 트랜잭션 다이어그램, 화이트 보드 사진 등을 넣은 장소)는 코드와 비슷하고 실행 불가능한 형식으로 간주합니다. 레코드는 코드 주석과 유사하지만 디자인시 선점 적으로 (테스트 가능한) 요구 사항이 지정됩니다. 아마도 당신이 민첩한 상점이라면 여전히 코드를 디자인하고, 마지막 순간에 코드를 작성하기 만하면됩니다. 이것을 다른 모든 프로젝트 문서와 함께 코드 기반으로 유지하십시오.

무엇을 하든지 검색 가능한 방식으로 저장해야합니다 (예 : 새 변경 사항을 지정할 때 "인증"과 관련된 모든 비즈니스 규칙을 풀고 싶을 수 있습니다).

항상 무언가를 쓸 때 의도 한 청중이 누구인지 스스로에게 물어봐야합니다. 저는 동료 개발자, 현재 또는 미래의 개발자를위한 디자인 문서가 있다고 확신합니다. 이 문서는 내가 무엇을 만들고 있는지, 무엇을 지 었는지 (높은 수준의 개요) 그리고 더 중요한 이유를 이해하는 데 도움이됩니다. 고려한 대안, 각각의 장단점을 문서화 할 수있는 곳입니다.

일부 디자인이 사람들의 두뇌 속에 사는 것이 좋다고 말하면 개발자들은 소중한 정보를 가지고 다른 직업을 찾고 다른 직업을 찾게됩니다.

코드를 유일한 디자인 문서로 만드는 것은 돋보기를 사용하여 도시를 돌아 다니는 것과 같습니다. 지도는 훨씬 더 유용합니다 (불행히도 소스 코드에 해당하는 GPS는 없습니다).

디자인 문서가 코드보다 훨씬 빨리 썩는다는 데 동의합니다. 그리고 둘 사이에 가능한 검증이 없기 때문에, 당신이 할 수있는 유일한 것은 그것들을 서로 가깝게 유지하는 것입니다. 날짜가 지정된 디자인 문서 인 IMO는 여전히 유용한 정보를 제공합니다.