적절한 양의 문서 결정

내가 현재 일하는 곳의 일반적인 접근 방식은-

가능한 한 문서화를 피하십시오

다른 팀이 필요로하는 경우에만 문서화

명확히하기 위해, 나는 코드 문서화를 의미하지 않습니다. 이것은 디자인 프로세스를 둘러싼 모든 문서를 의미합니다-UML 또는 DB 스키마, 클래스 다이어그램 및 사양과 같은 단어 문서 인 경우.

나는 상사의 이유를 문서화하지 않을 것입니다 :

1. 시간이 많이 걸립니다-구현에 집중
2. 디자인 변경-문서가 변경되면 두 번 문제
3. 결국 당신은 아무도 읽고 싶지 않은 수백 페이지를 얻습니다.
4. 그 고통-아무도 정말로 그것을 원하지 않습니다.

이제는 우리가 더 빨리 일한다는 것을 알고 있지만, 아무것도 이해하지 못하고 여기에 와서 오래된 코드로 바로 뛰어 들었던 시간을 기억합니다.

사실, 나는 여전히이 오래된 코드를 얻지 못하고 때로는 들어가면 다른 개발자가 작은 수정을 시도하는 많은 패치를 보게됩니다.

문서화가 부족하면 이러한 종류의 패치와 시스템 이해의 부족이 광범위한 의미에서 촉진된다고 생각합니다.

내 질문은 :

팀 간의 지속적인 지식을 증진시키고 여전히 빠르고 효율적으로 문서화의 균형을 잡는 방법은 무엇입니까?

모든 문서가 NO 문서보다 낫다는 것을 알았습니다. 적절한 금액은 보통 우리가해야 할 시간 또는 전화 및 이메일 지원을 얼마나 싫어하는 지에 따라 결정됩니다.

현재 팀원들은 자신의 기억에 대한 비현실적인 기대를 가지고 있거나 작문 기술이 부끄러워서 연습하기를 원하지 않는 것 같습니다.

나는 문서로 집안일을 찾을 수 없기 때문에 나는 여기에 소수 (대학원에서 소프트웨어 공학을 전공 한 영어 전공)에 있다는 것을 알고있다. 귀중한 전문 도구입니다. 나는 동료들처럼 글쓰기가 어렵다는 것을 알지 못할 수도 있지만, 그보다 더 많은 연습을했기 때문입니다. 나는 문서가 없으면 완성 된 프로젝트를 고려하지 않고 보통 이기적인 이유로 글을 씁니다. 그래서 사람들에게 전화 나 이메일을받는 대신 읽을 것을 줄 수도 있고, 마지막에 이야기했던 것을 기억할 수도 있습니다 한 달에 한밤중에 지원해야한다면 어떻게했는지 참고할 수 있습니다.

문서에 접근하는 가장 좋은 방법은 테스트 코드 작성과 마찬가지로 원하는대로 작성하는 것입니다. 미리 작성된 몇 가지 템플릿 (헤더, 코드 스텁 등)으로 문서를보다 쉽고 빠르게 만들 수있는 방법이 놀랍습니다. 이렇게하면 변경 사항이 발생할 때이를 포착 할 수 있으며 시간이 지남에 따라 적용 범위가 줄어 듭니다. 필요에 따라 문서를 참조 할 수 있고 변경하면서 문서를 변경할 수 있으므로이 방법이 더 효율적입니다. 예를 들어, 위키에서 그렇게하면 업데이트가 쉬워지며 최신 버전과 최고 버전이 항상 같은 장소에 온라인 인 경우 문서 버전 문제를 피할 수 있으며이를 읽어야하는 사람들에게 링크를 보낼 수 있습니다.

문서화에 약간의 시간을 소비한다면, 특히 새로운 누군가가 팀에 합류 할 때 모든 것이 더 빨리 작동 할 것입니다. 왜냐하면 그들은 모든 시간을 다 소비 할 필요가 없기 때문입니다. 물건을 알아내는 것은 우리 작업의 재미있는 부분이지만, 생산을 수정하기 위해 서둘러해야 할 때는 재미가 없습니다. 우리가 둘 다 더 많은 메모를 쓴다면 우리 모두는 많은 시간을 절약 할 것입니다.

팀에서 테스트 또는 테스트 코드 작성과 동일한 문제가 있습니까? 그렇지 않은 경우, 더 쉽게 판매 할 수 있습니다.

이 문서는 여러 가지면에서 유용합니다.
1) 프로젝트를 진행하면서 지금 당장 그리고 동료에게도 유용합니다 .

2) 고객에게. 사용자에게 보여줄 수있는 문서 (다이어그램 포함)가 있으면 특히 복잡한 시스템에 대해 토론 할 때 회의에서 더 쉽게 토론 할 수 있습니다. 문서가 불완전하더라도 처음부터 시작해야합니다.

3) 당신의 일을 물려받을 사람들에게 (3 년 안에 당신 일 수도 있습니다). 저의 젊은 동료들 중 많은 사람들은 그들이 영원히 기억할 것이라고 생각합니다. 적어 두지 않으면 지난 주에 기억이 나지 않습니다. 문서를 작성하면 무언가를 구성한 방식을 기억하기 위해 반나절을 소비하고 다시 계산해야하는 시간을 절약 할 수 있습니다.

4) 상황이 정치적이거나 논쟁적인 경우 귀하와 타인에게. 회의에서 메모를하는 사람으로서, 깨어 있고 지루함을 없애기 위해, 나는 종종 서면 판결을 가진 유일한 사람이었습니다. 적어 둔 사람이 분쟁에서 이깁니다. 다음에 누군가가 "X를 지나갈 때 회의실 4에서 지난 겨울에 있었던 모임을 기억하십니까? 프레드가 거기 있었는데 그 사람은 누구입니까?"

마지막 몇 명의 고용주에게 "개발"위키가있었습니다. 중요한 기능 (새로운 가져 오기 / 내보내기 피드, 보안 하위 시스템 작동 방식, 업로드 된 문서를 저장하는 위치 등)이 모두 문서화됩니다. 일반적으로 코드 검토 단계 전에 완료해야하는 필수 항목입니다. 처음에는 일반적으로 약간의 저항이 있지만 누군가가 약간의 정보를 찾아야하고 거기에 있으면 다른 개종자가 있습니다.

위키 형식으로 사용하는 것의 좋은 점은 모든 예쁜 Word 형식을 수행하고 저장 해야하는 실제 정보를 작성하는 경향이 훨씬 적다는 것입니다. 대부분의 위키 패키지를 사용하면 Visio UML 다이어그램 또는 UI 와이어 프레임과 같은 문서 나 이미지를 업로드 할 수 있으므로 시각적 인 부분도 가질 수 있습니다.

대부분의 것들과 마찬가지로, 가능한 한 최소한의 일을하는 것이 목표라고 생각합니다. 그래도 다른 것과는 다릅니다.

적절한 문서를 작성하기 위해 시간을 할당하지 않아도됩니다. 그러나 얼마나 많은 일을했는지에 따라 균형을 맞추십시오. 그러나 자신이 한 일을 문서화하려면 시간의 15-20 %를 남겨 두십시오. 팀의 모든 사람은 관리자를 포함하여이 일에 동참해야합니다. 그렇지 않으면 다른 사람의 이익을 위해서만 문서화 할 것이며 아무런 대가도받지 못할 것입니다. 문서화는 개발 프로세스의 필수 부분이어야합니다.

문서는 HOW 파트를 실제 코드로두고 WHAT 파트를 단위 테스트로 두는 동안 왜 무언가를했는지 알려줍니다. 더 이상은 고통입니다. 이것은 보통 출발점을 원하는 똑똑한 사람들에게 충분합니다.

또한 코드 기반의 각 큰 구성 요소에 대한 전반적인 높은 수준의 아키텍처를 유지하는 것을 잊지 마십시오. 새로운 팀원을 쉽게 유도 할 수 있습니다.

마지막으로, 이상한 수정을 추가 할 때마다 주석에서 버그 데이터베이스에 연결하십시오-매우 유용합니다.

당신의 상사가 옳은 사람은 아무도 읽을 수없는 UML 문서를 인쇄하지 않습니다. 우리 팀에서하는 일은 클래스 다이어그램 뷰를 사용하여 모델을 실시간으로 탐색하는 것입니다. 원칙은 항상 코드에서 실시간으로 UML 모델 인 MOF를 업데이트하고 클래스 다이어그램은 모델의 뷰어 일뿐 모델 자체는 아닌 것입니다.

백 오피스의 모든 복잡성이 모델 수준에서 이루어지기 때문에 실제로 잘 작동합니다. 내 프로젝트를 리팩터링하거나, 자바 문서를 작성하거나, 모델에서 uml 문서를 작성할 수 있습니다. 클릭 앤 고의 종류입니다. 클릭하면 라이브 문서를 얻습니다. 무언가가 명확하지 않으면 수업 다이어그램을 열고 게임을 시작합니다. 다이어그램 분류기에서 삭제, 새 분류기 추가, 확대 및 축소, 연관 표시, 연관 삭제 등 ... 새 모델 정보를 작성하지 않기 때문에 모델이 변경되지 않습니다.

패키지 다이어그램을 열고 클래스 다이어그램에서이 클래스의 내용에 대한 주석을 직접 읽을 수 있어야합니다. 이 방법으로해야 할 일과 흐름 등

UML은 훌륭하고 실제로 유용하지만 모델링 / 개발 단계에서 더 많은 유연성과 반복을 제공하기 위해 Model Driven Devleopment 사용을 중단해야합니다. 클래스 다이어그램은 코드에서 실시간으로 업데이트되며 설명서는 항상 정확하고 클릭 한 번으로 제공됩니다. 도구를 언급하지는 않지만 Java 및 Eclipse를 사용하는 경우 사용하는 도구를 쉽게 찾을 수 있습니다 :-)