태그 보관물: documentation

documentation

애자일의 일부로 문서 디자인 우리는 일반적인 개선 노력으로이를 해결하려고 노력하고

직장에서는 “애자일”이 너무 자주 “모호한 요구 사항, 잘못된 수용 기준, 행운을 의미”한다는 의미에서 어려움에 직면합니다. 우리는 일반적인 개선 노력으로이를 해결하려고 노력하고 있습니다.

따라서 그 중 일부로서 사용자 스토리 수준 이상으로 시스템 내에서 주어진 기능의 영향에 대한 예비 조사 결과를 정확하게 반영하고 우리가 가진 질문에 대한 답변을 포함하는 디자인 문서를 생성 할 것을 제안합니다 사업을 물었다.

이에 대한 효과적인 표준이 있습니까?

우리는 현재 새로운 기능이 “큰 진흙 투구” 시스템 여러 영역에 영향을 미칠 수있는 상황에 직면 해 있으며 이러한 기술적 부채로 인해 추정치가 상승하기 시작했습니다. 더 사려 깊은 디자인 프로세스가 도움이 될 수 있기를 바랍니다.



답변

“모호한 요구 사항, 잘못된 승인 기준, 행운을 빈다!”

,, 이것은 당신이 그들을 쓰려고하더라도 당신이 얻는 것과 같은 종류의 요구 사항입니다! (예를 들어, 정부 고객이 4 년이 걸렸던 10,000 개의 요구 사항 문서는 여전히 불일치, 모호함 및 심지어 내부적으로 모순되는 진술로 가득 차있었습니다. 모호하지 않은 것을 얻을 수 있다고 생각하십니까?)

그래서 … 민첩한 방법은이 문제가 발생한다는 것을 이해하고 그에 대항하려고 노력하기보다는 그와 함께 일하기 위해 고안되었습니다.

“무엇을 원하십니까”를 물어 보면 고객이 “이와 비슷한 것”으로 응답합니다. 몇 가지 작업을 수행 한 다음 고객에게 돌아가서 “이것이 원하는 것입니까?”라고 말하고 고객은 일반적으로 “그렇지만 …”이라고 말합니다.

결국 고객은 그것이 무엇인지 모르더라도 고객이 원하는 것을 정확하게 얻습니다! (지옥, 그들은 결코 그들이 원하는 것을 알지, 정확히).


답변

우리 팀은 민첩한 이후 실제로 필요한 문서의 양을 좁히고 이해하려고 노력했습니다. 지금까지 배운 내용을 알려 드릴 수 있습니다.

무엇보다 먼저 애자일 / 린 문서 에서이 기사 를 읽으십시오 . 아주 잘 읽었습니다.

둘째, 스토리에 대한 예비 작업을 마친 후 디자인 문서 제작을 재고 할 것을 강력히 권합니다. 우리는 전에 그것을 시도했고 그것은 낭비 인 것으로 판명되었습니다. 마지막 릴리스 중간에 스토리의 코드가 제공된 후에 만 ​​디자인 문서를 업데이트하기로 결정했습니다. 그리고 지금은 너무 빠르다고 생각합니다.

코딩하기 전에 왜 디자인 문서를 만들고 싶은지 스스로에게 물어봐야합니다. 우리에게는 이것이 이유였습니다.

  1. 우리 팀은 스토리가 디자인에 어떤 영향을 미치는지 이해해야합니다.
  2. 새로운 (또는 임시) 멤버가 팀에 합류하거나 1 년 이상 아무도 작업하지 않은 코드로 돌아올 때 디자인 문서가 유용하다는 것이 입증되었습니다. 따라서 코드가 작동하는 방식을 이해하는 데 도움이되는 조직 메모리에 유용합니다.
  3. 디자인 문서는 릴리스 후 코드 문제를 해결해야하는 유지 관리 엔지니어에게 유용합니다.

(1)을 만족시키기 위해 실제 디자인 문서를 작성할 필요는 없습니다. 팀은 코딩하기 전에 디자인 단계를 수행해야하지만 화이트 보드 나 냅킨 앞에서 15 분의 세션만큼 간단 할 수 있습니다. 설계 변경 사항을 논의하기 위해 작성하는 데 몇 시간 (몇 일이 아닌 경우)이 걸리는 실제 문서를 작성할 필요는 없습니다.

(2) 또는 (3)은 현재 스토리를 개발하는 동안 필요하지 않으며 이후의 여러 반복에 필요하지 않을 가능성이 높습니다.

또한 팀 구성원이 디자인 문서를 작성 / 업데이트 할 때마다 코드가 작성되지 않는 시간입니다. 실제 코드 전에 문서를 작성할 때는 코딩을 시작하면 디자인이 항상 변경되기 때문에 업데이트해야 할 확률이 거의 100 %에 이릅니다. 코드를 작성한 후에도 디자인 문서를 작성하더라도 팀에서 배운대로 후속 스토리를 리팩토링하면 디자인이 변경됩니다.

그래서 내가 추천하는 것 :

  1. 코딩하기 전에 팀이 지능적인 대화를 할 수 있도록 초기에 임시 디자인 / 모델을 제작하십시오. 이것들을 지키지 말고 공식화하는 데 시간을 낭비하지 마십시오.
  2. 누군가가 필요할 경우에만 공식 설계 문서를 작성하십시오 (예 : 팀에 조직 메모리가 실제로 필요함)
  3. 안정화 된 코드에 대해서만 설계 문서를 작성하십시오. 반복 할 때마다 계속 변경되는 모듈을 문서화하려고 시도 할 필요는 없습니다.
  4. 모듈 (또는 제품의 일부)을 완전히 설명하는 설계 문서를 작성하십시오. 과거에는 변경 사항을 문서화 한 디자인 문서를 작성했습니다. 해당 문서는 릴리스가 완료 되 자마자 완전히 쓸모가 없었습니다.
  5. 문서를 매우 높은 수준으로 유지하십시오. 아키텍처와 매우 높은 수준의 디자인을 다루는 20 페이지를 작성하는 경우 해당 문서는 a) 실제로 다른 사람이 읽고 b) 사람들이 일반적인 코드 레이아웃에 익숙해 지도록 도와줍니다. 자세한 내용은 사람들이 직접 코드로 들어갈 수 있습니다. 자세한 사양의 700 페이지를 작성하면 거의 항상 실제와 일치하지 않을 것입니다. 누구나 읽을 수 없을만큼 많아 향후 변경 될 때마다 20 페이지 대신 700 페이지를 유지 관리하고 업데이트해야합니다.

답변

애자일 “만트라”는 문서화 없이는 할 수 없습니다.

애자일 만트라는 ” 포괄적 인 문서보다 작업 소프트웨어 “를 선호합니다 . 그러나 선언문의 맨 아래에있는 비트에 유의하십시오.

즉, 오른쪽에있는 항목에는 가치가 있지만 왼쪽에있는 항목은 더 중요하게 생각합니다. “

Bob 아저씨는 문서화에 대한 좋은 정책을 가지고 있습니다

즉각적이고 중요하지 않은 한 문서를 작성 하지 마십시오 .

어떤 사람들은 문서를 작성하지 않은 것에 대한 변명으로 애자일을 사용하는 것이 맞습니다. 그러나 그것은 나쁜 애자일입니다. 위의 따옴표에서 강조 표시된 비트는 무시합니다.

“현재 우리는 새로운 기능이”큰 진흙 투구 “시스템의 여러 영역에 영향을 줄 수있는 상황에 처해있다”고 말할 때 애자일이 되려면 이와 관련하여 무언가를해야합니다.

설명서가 있으면이를 사용하여 코드를 모듈화하십시오. 이렇게하면 문서에 대한 장기적인 필요성을 제거하여 문서를 유지 관리해야 할 장기적인 필요성을 제거 할 수 있습니다.

즉. 즉각적이고 중요한 필요성을 확인하십시오.


답변

민첩한 점은 문서화 노력이 실제로 스크럼 팀에 의해 추진되어야한다는 것입니다. 개발자가 외부 문서만으로는 충분하지 않다고 느끼면 사용자 스토리가 끝날 때까지 차단됩니다. 비즈니스에서 개발자가 적절한 문서를 작성하지 못한다고 생각하면 제품 소유자는 해당 문서를 승인 기준의 일부로 만들어야합니다. 이 때문에 스크럼으로 이동 한 이후로 문서가 더 집중되고 효과적이라는 것을 알았습니다.

우리는 VersionOne 을 사용 하여 사용자 스토리를 추적하지만, 우리의 방법이 다른 시스템에 적용될 것이라고 확신합니다. 사용자 스토리에 파일을 첨부 할 수 있습니다. 우리는 디자인 문서를 넣을 때 매우 유용한 곳이라는 것을 알았습니다.

우리에게 정말 효과가 좋은 예를 들어, 프로토 타입을 제작 한 후 가능한 빨리 새로운 회로 보드 설계를 테스트해야했습니다. 테스트가 필요한 모든 것에 대해 두 가지 사용자 스토리를 만들었습니다. 하나는 테스트를 디자인하고 다른 하나는 테스트를 실행하는 것입니다. 디자인 스토리에 대한 수용 기준 중 하나는 테스트 절차가 실행 스토리에 완전히 문서화되어 있다는 것입니다.

우리가 테스트 부분에 도착했을 때, 그것은 내가 본 것보다 더 부드럽게 진행되었습니다. 방금 사용자 스토리를 열고 단계별 절차를 수행했습니다. 문서는 우리가 이야기를 완성하는 데 필요한 것이 었습니다.

우리는 백 로그에 다른 팀이 자신의 제품을 위해 쉽게 선택할 수 있도록 사용하는 칩의 문서를 개선하기위한 또 다른 이야기를 가지고 있습니다.

요약하자면, 문서가 어려움을 겪고 있다고 생각되면 솔루션은 별도의 사용자 스토리를 작성하거나 승인 기준의 일부로 만드는 것만 큼 쉽습니다.


답변

열악한 요구 사항에 대해 말할 때 가장 먼저 떠오르는 것은 테스트 기준이 있는지 확인하는 것입니다. 가능하면 시스템의 기존 부분에 대해 재사용 가능한 자동화 테스트 사례를 작성하십시오. 모든 사람들이 그것에 익숙해지면 코드를 작성하기 전에 테스트 사례 작성으로 이동하십시오. 좋은 테스트 사례는 시스템의 동작을 문서화하는 데 많은 도움이 될 수 있습니다.

다른 사람들이 이미 언급했듯이 사용할 특정 디자인 문서에 대해서는 팀의 요구와 그들이 수행 할 다음 작업에 크게 의존합니다. 가능하면 사용할 코드를 사용하여 문서를 생성하거나 문서에서 코드를 생성 할 수있는 도구를 사용하십시오. 문서 관리는 비용이 많이들 수 있으므로 디자인 문서를 유지할 때는 현명하게 선택하십시오.

개인적으로 저는 코드 및 fitnesse 테스트 사례에서 생성 된 클래스 다이어그램을 성공적으로 사용했습니다. 팀은 몇 가지 클래스 다이어그램을 인쇄하고 제품 소유자와 마크 업 세션을 수행 한 다음 견적을 작성합니다. fitnesse가 진행되는 한, 스프레드 시트에서 원하는 것을 표현하는 데 능숙한 두 명의 제품 소유자와 함께 일한 후 fitnesse를 위해 테이블로 변환하는 것이 행운입니다.


답변