설계 문서에 주어진 설계에 대한 장단점에 대한 논의가 포함되어야합니까, 아니면 사실과 근거에 초점을 두어야합니까?

현재 설계 문서를 업데이트하여 향후 개발자에게 정확하고 최신 상태입니다.

현재이 문서는 사실에 중점을 두어 설계 방식을 제시합니다. 제시된 결정에 대한 근거는 없습니다. 필자는 이론적 근거를 파악하여 개발자가 무언가가 왜 그런지에 대한 이유를 알도록함으로써 미래의 결정에 영향을 미칠 수 있다고 생각합니다. 모든 설계 결정, 특히 프로젝트 작업을 시작하기 전에 이루어진 결정에 대한 이론적 근거를 추가 할 수는 없지만이 부서에서 할 수있는 일을하고 있습니다.

그러나 디자인 결정 중 일부는 프로젝트 요구 사항을 감안할 때 매우 잘못된 결정입니다. 하지만 좋은 것도 있습니다.

저의 초기 생각은 미래의 관리자들에게주의를 집중시키기 위해 디자인 문제와 잠재적 솔루션 또는 이러한 문제에 대한 해결책을 포함시켜야한다고 생각했지만 디자인 문서가 이러한 유형의 토론과 정보를위한 장소인지 확실하지 않습니다. 다른 사람들이이 시스템에서 작업하고 문서를 업데이트 할 때 "이 디자인을 새로운 디자인으로 리핑"하기 위해 디자인 "비평"을 원하지 않습니다.

관리자는 두 가지 결정을 모두 지원하므로 본인에게 달려 있습니다. 내가 취한 접근 방식에 관계없이, 제작 된 문서는 공식적으로 버전이 지정되고 시스템을 개발하는 개발자에게 일반적으로 개발 작업을하기 전에 제공됩니다. 새로운 개발자는 개발 작업을 시작하기 전에 주어진 소프트웨어 시스템과 관련된 문서를 숙지해야합니다.

질문 :

• 디자인 문서가 실제 사실 ( "이것은 디자인")과 이론적 근거 ( "이것이 디자인 인 이유")에 충실해야하거나 문제가 될 수있는 디자인에 결함이없는 문제를 지적하는 데에도 사용되어야합니다. 미래 개발자?
• 디자인 문서를 사용하여이 정보를 캡처하지 않아야하는 경우, 어떤 유형의 문서를 캡처해야하는지, 그리고 설계 근거, 트레이드 오프 및 알려진 문제 (결함이 추적되지 않으므로 결함이 아닌)에 대한 논의를 통해 캡처해야 할 사항 다른 도구를 사용)?

장단점을 한두 문장으로 요약 할 수 있다면 디자인 문서에 넣는 것이 좋습니다. 더 이상 무엇이든 분리해야합니다.

내가 현재 일하는 곳에서는 일반적으로 모든 중요한 결정을 추적하기위한 별도의 "디자인 결정"문서가 있습니다. 문제가있는 단락으로 형식이 지정된 경우가 종종 있습니다 (예 : "일부 파일은 각 처리주기가 끝날 때 서버에서 특정 사용자로 이동해야합니다. 여러 가지 방법이 있습니다 ..."), 열이있는 테이블 " 솔루션 설명 "(예 :"FTP를 통한 파일 이동 "),"프로 "(예 :"사용자가 관리하기 쉬움 "),"cons "(예 :"ABC-XYZ 준수를위한 보안이 충분하지 않음 ") 및 결론 특정 결정이 선택된 이유를 설명합니다 (예 : "FTP는 특정 규정 준수 요구 사항을 충족 할 수 없기 때문에 사용되지 않습니다"). 설계 문서는 일반적으로 선택한 결정 만 참조합니다.

디자인 문서가 실제 사실 ( "이것은 디자인")과 이론적 근거 ( "이것이 디자인 인 이유")에 충실해야하거나 문제가 될 수있는 디자인에 결함이없는 문제를 지적하는 데에도 사용되어야합니다. 미래 개발자?

"또는 둘다"가 아닙니다.

아무도 처음부터 문서를 읽지 않습니다. 그들은 뛰어 넘습니다. 따라서 가능한 적은 문서를 작성하십시오. 하나의 문서는 누구나 인내심이 있습니다. "기타 문제"가 포함 된 두 번째 "비논리적"문서는 전혀 읽을 수 없습니다.

한 문서의 장점? 사람들은 그것을 읽을 수 있습니다.

한 문서의 단점? 조금. 대부분 구식입니다.

여러 문서의 장점? 없음

여러 문서의 단점? DRY 원칙과 읽기 쉬운 프로그래밍을 읽으십시오. 여러 문서는 여러 가지 오류 원인을 의미합니다. 각 문서는 다른 문서에 동의하지 않으며 코드에 동의하지 않습니다. 이것은 분명하다. 이것이 광기의 길입니다.

손으로 묶지 마십시오.

장단점 문서는 가정과 매력적인 성가신 토론의 무한한 깊이로 끌어들일 수 있습니다.

찬반 양론을 제시해야한다고 생각되면 짧고 요점을 지키십시오.

무엇에 집중하십시오.

베어 본이 아닌 것을 보관하십시오.

벤치 마크, 연구 또는 실제로 대안을 탐색 한 경우이를 문서화하십시오. 그러나 대안을 고려하고 있다면 최소화하십시오.

이것은 당신의 시련과 환난의 역사가되어서는 안됩니다.

• 문제가 있었나요? 고쳤다? 몇 주가 걸렸습니까? 정말 힘들었나요? 간신히 흥미로운 일화. 코드에서 수정되었습니다. 이전 버전, 잘못된 버전, 버기 버전 ​​및 저 성능 버전은 중요하지 않습니다. 그들은 블로그 블로그입니다.

• 여전히 문제가 있습니까? 수정되지 않았습니까? 그것은 대안이 있다는 것을 의미합니다. 이것을 문서화하십시오.

의사 결정 과정에는 3 가지 중요한 사실이 있습니다.

• 시도했지만 작동하지 않은 대상 (그리고 움직이는 대상을 대상으로하기 때문에 작동하지 않는 이유)
• 뭐가
• 무엇인가 (X가 구현되기를 기다리는 중 ...)

그러나 "What is"와는 별도로 다른 모든 사용자는 독자를 혼란스럽게하고 시스템을 방황하지 못하게합니다.

나는 다른 두 가지를 캡처한다는 아이디어를 좋아하지만 시스템을 배우는 데 덜 흥미 롭지 만 변경하면 시간을 절약 할 수 있습니다.

따라서 @FrustratedWithFormsDesigner에 노출 된 아이디어를 꼬아 서 만들었습니다. 수명주기가 다른 문서를 작성하는 대신 부록 섹션을 작성하려고합니다. 그런 다음 토론 할 가치가있는 각 결정에 대해 부록의 관련 항목을 지적하겠습니다.

예. 설계 문서는 설명 된 설계와 관련된 이점, 위험 및 가정을 설명해야합니다. 디자인 문서에는 여러 가지 목적이 있습니다.

1. 모든 사람이 이해하고 시간이 지남에 따라 각 사람의 이해가 표류하지 않도록 디자인을 작성하십시오.

2. 프로젝트를 수행하는 비전문가에게 디자인을 알리십시오.

3. 스케줄링, 자원 할당, 비용 추정 및 기타 종류의 계획을 지원합니다.

4. 전체 프로젝트 문서의 중요한 부분이됩니다. 진행중인 프로젝트에 참여하거나 완료된 프로젝트를 유지 관리해야 할 때 잘 작성된 디자인 문서가 있으면 인생이 훨씬 쉬워집니다.

5. 종종 계약에 필요한 결과물 중 하나입니다.

(아마도 다른 것이있을 수 있지만 좋은 출발입니다.)

이러한 목적 중 하나는이 디자인이 선택된 이유와 관련 위험이 무엇인지 명확하게 설명하는 디자인 문서에서 잘 제공됩니다.

1. 팀의 모든 사람이 위험과 이점이 무엇인지 파악하여 이러한 위험을 피하고 디자인의 이점을 최대한 활용할 수 있도록 함께 협력 할 수 있어야합니다.

2. 비 기술적 인 팀 구성원의 경우 위험과 이점을 이해하는 것이 디자인 자체의 특정 사항보다 더 중요한 경우가 많습니다.

3. 위험 관리는 프로젝트 관리자가 성공을 보장하기 위해 할 수있는 가장 중요한 일 중 하나이며 첫 번째 단계는 관리해야 할 위험을 식별하는 것입니다. 위험을 처리하는 방법을 결정하는 것은 관리자의 책임이지만, 설계의 알려진 위험을 지적하는 것은 디자이너의 책임입니다.

4. 위험이 더 이상 문제가되지 않더라도 디자인을 만들 때 상황을 설명하는 데 도움이되므로 문서화하는 것이 유용합니다. 따라서 관리자는 다음과 같이 결정할 수 있습니다. "좋아요. 이전에는 이런 식으로했지만 ... 더 이상 문제가되지 않으므로 더 간단하고 빠른 구현으로 코드를 대체 할 수 있습니다." 물론 혜택도 마찬가지입니다.

5. 고객을 위해 프로젝트를 진행하는 경우 위험과 이점을 문서화하는 것이 특히 중요합니다. 따라서 고객은 특정 상황에서 문제가 발생할 수 있거나 디자인 변경을 요청하면 약속 된 이점 중 일부를 위태롭게 할 수 있음을 알립니다.

이미 구현 된 시스템의 기존 설계 문서로 작업하고 있다는 질문에서 수집합니다. 이 경우 가능한 많은 위험이 더 이상 위험이 아니므로 사실 이후에 문서화하려고 시도하는 것은 의미가 없습니다. 그러나 원래 디자인에서 제대로 작동하지 않는 부분을 볼 수 있으므로 이제 가늠자의 이점이 있습니다. 현재 문제 영역을 식별하고 해결책 (관련 위험 포함)을 제안하는 별도의 섹션을 추가해야합니다. 또는 같은 일을하는 별도의 문서를 작성하십시오. 이 새로운 섹션 / 문서는 다음 버전의 소프트웨어를위한 디자인 문서로 발전 할 수 있습니다.

다음 은 도움이 될만한 디자인 문서 작성에 대한 블로그 항목입니다 .

보다 명백하거나 표준적인 솔루션을 피해야 할 정당한 이유가있는 경우에는 그 점에 유의해야합니다. 당신은 많은 사람을 구할 수 있습니다. 그러나 특정 기술은 시간이 지남에 따라 개선 될 수 있으므로 귀하의 사유가 적용되지 않을 수 있습니다. 미래 개발자는 자신의 판단을 사용할 수 있습니다.

모든 단점을 지적하는 데 많은 이점이 있는지 모르겠습니다. 변경하거나 다른 우선 순위가 적용되는 것은 실용적이지 않을 수 있습니다. 가까운 시일 내에 일부를 고칠 수 있으며 업데이트해야 할 사항이 하나 더 있습니다.

나는 개인적으로 디자인 문서에 넣지 않을 것입니다. 설계 문서는 그 이유가 아니라 그 상태를 간략하게 설명해야합니다.

디자인이 왜 그런지에 대해 뒷이야기가 필요하다고 생각되면 위키 기사 (또는 회사가 사용하는 모든 지식 기반)에 기록을 작성하여 디자인의 진화. 사람들은 가서 읽고, 편집하고, 제안을 추가 할 수 있습니다. 그렇게하면 문서에서 눈썹이 치는 대신 열린 토론에 더 가깝습니다.

디자인 문서에 근거를 두는 것에 동의합니다.

어쨌든,

다른 사람이 작성한 디자인 문서를 업데이트하는 과정에서 나는 겸손하게 지내고 왜 그런 결정이 내려 졌는지 추측하려고하지 않을 것입니다.

그래서,

유지 관리 중 디자인에서 변경 한 내용에 대한 이론적 근거 만 삽입합니다.