'문서'는 정확히 무엇을 구성합니까?

우리가 소프트웨어 제품에 대한 '문서'를 말할 때, 그 내용에는 무엇이 포함되어 있지 않아야합니까?

예를 들어, 최근 질문에서 의견이 문서로 간주되는지 물었습니다.

그러나 이것도 유효한 질문이며 다른 것보다 더 분명한 많은 다른 영역이 있습니다.

• 매뉴얼 (분명히)
• 릴리즈 노트?
• 튜토리얼
• 코멘트
• 다른 사람?

선은 어디에 있습니까? 예를 들어, 'tutorial'이 문서 인 경우 'video tutorial'문서입니까, 아니면 다른 것입니까?

일반적으로 소프트웨어의 일부는 구현, 테스트 및 문서화 될 때까지 '완료'되지 않습니다. 따라서이 질문은 무엇인가를 '완료'로 간주하기 위해 문서화의 일부로 고려해야 할 사항입니다.

_{회의에서 최근 고객 의견을 통해 의사가 문서에 더 많은 '샘플'이 필요하다는 것을 알 수있었습니다.}

_{대상 : 데이터베이스, 프로그래밍 언어 및 관련 툴링 (예 : 해당 DB의 관리자 클라이언트)을 사용하는 소프트웨어 개발자}

설명서의 목표는 소프트웨어 제품을 설명하고 설명하는 것이므로 설명서를 해당 설명이나 설명에 기여하는 일련의 인공물로 정의 할 수 있습니다. 문서의 일부로 관련 조치 를 고려하지 않을 것입니다 . 예를 들어 1 주일 동안 진행되는 교육 과정은 문서가 아니라 과정 자료입니다. 5 분 화이트 보드 채팅은 문서화가 아니라 화이트 보드 이미지입니다.

소프트웨어를 설명하는 목표를 염두에두고 고객이 소프트웨어에 만족할 때 소프트웨어가 완성 된 것처럼 고객이 설명에 만족 하면 문서가 완성됩니다 . 설명서의 고객이 소프트웨어를 지불하는 고객과 항상 같은 것은 아니라는 점에 유의하십시오. 지원 담당자, 테스터, 영업 사원 및 기타 사람들은 소프트웨어의 기능과 작동 방식에 대한 이해가 필요합니다.

이를 통해 문서에 포함해야 할 경계가 어디에 있는지 이해하는 데 도움이됩니다. "독자"를 편리한 속기로 사용하지만 비디오 나 오디오를 포함 할 수 있음을 인정합니다. 독자가 소프트웨어에 대해 필요한 정보를 얻는 데 도움이되는 것은 사용할 수있는 문서 일뿐, 그 밖의 모든 것은 아닙니다. 고객에게 모든 사용 사례에 대한 자세한 설명이 필요한 경우 문서의 일부가되어야합니다. 개발자는 아마도 소스 코드, 버전 관리 리포지토리에 대한 정보 및 빌드 지침이 필요할 것입니다.이 문서는 설명서이지만 위에서 설명한대로 고객 설명서의 일부는 아닙니다.

나는 당신이 회의에서 대화에서 잘못된 부분을 빼앗 았다고 생각합니다. 최신 소프트웨어 개발 방법론에서는 개발 팀이 고객 (또는 고객 프록시 역할을하는 제품 소유자)과 긴밀하게 협력해야한다고 주장합니다. 전달 된 모든 작업에서 "완료"의 정의는 팀과 고객간에 협상되는 것이며 소프트웨어가 개발 될 때 반복적으로 수행됩니다.

문제는 고객이 필요하다고 생각한 것과 고객이 제공 할 것으로 예상 한 것 사이에 연결이 끊어져서 결국 "모든 샘플이 어디에 있습니다"라는 놀라움을 느꼈다는 것입니다.

지금까지 문서 란 무엇입니까? 글쎄, 그것은 당신이 나열한 거의 모든 것, 그리고 당신이하지 않은 몇 가지 더 많은 것입니다. 그러나 아무도 프로젝트에 필요한 문서의 양을 말할 수 없습니다. 모든 프로젝트는 다르며 프로젝트에 필요한 문서의 수준과 유형을 결정하는 것은 팀, 제품 소유자 및 고객의 몫입니다.

작용할 몇 가지 요소 :

• 소프트웨어 v1.0을 개발 중이며 다른 프로젝트로 넘어 가고 있습니까? 아니면이 지속적인 장기 프로젝트입니까? 후자의 경우 주석 / 디자인 문서가 훨씬 더 중요해집니다. 반면에 고객이 엄마와 팝 도넛 가게이고 당신이 볼 수없는 웹 사이트를 작성하는 경우 ... 글쎄, 코드 문서는 훌륭하지만 그렇게 중요하지는 않습니다.
• 병원에서 심박수 모니터를 제어하는 ​​모바일 게임 또는 소프트웨어를 개발하고 있습니까? 어느 쪽이 더 많은 문서를 가지고있는 "완료"에 대한 정의를 가지고 있을까요?
• 고객이 일반적인 최종 사용자입니까, 아니면 다른 개발자입니까? 노출중인 API / SDK가 있습니까?
• 고객의 전문 지식 수준은 무엇입니까? 이것은 비디오 튜토리얼 대 글 자료 대 대화 형 튜토리얼 앱의 선택에 영향을 미칩니다.
• 고객이 버전마다 변경된 사항에 관심을 갖도록하십시오. 일부는 그렇습니다. 대부분 그렇지 않습니다. 소수의 사람들은 돌봐야 할 법이 있습니다.

문서는 수정하지 않고 읽도록 작성된 것입니다.

나는 당신이 목적에 기초한 정의에 잘못 될 수는 없다고 생각합니다. 그러나 당신이 목적을 올바르게 정의해야만 가능합니다.

• ^{문서 목적을 올바르게 정의하는 것은 그리 간단하지 않습니다. 당연히 염두에 두어야 할 간단한 점은 문서는 읽기를위한 모든 것이지만, 비교를 위해 코드는 컴퓨터 실행을위한 모든 것입니다 . 표면이 좋지 않습니까? 그러나 더 깊이 파고 나면 정말 추악합니다.
   
  좋은 코드는 실행 정확성과 함께 가독성 문제를 고려합니다. 이는 문서 정의에있어 "가독성"구별을 거의 쓸모 없게 만듭니다. 당신이 언급 한
   
  바로 그 샘플 들은 그에 문제가 있음을 보여줍니다. 고객은 일반적으로이 내용이 명확하게 작성 되고올바르게 실행하십시오. 가독성이나 정확성이 저하되면 고객 불만이 발생할 수 있습니다. 순진한 구별은 샘플이 코드인지 문서인지 파악하는 데 도움이되지 않습니다. 오픈 소스로
   
  작업하는 것을 상상한다면 순진한 구별을 사용하면 훨씬 더 지저분해질 것 입니다. 당신은 그것을 다운로드하고, 빌드하고 실행합니다-당신은 그것을 읽지 않습니다, 그것은 단지 코드입니까? 잠깐, 어떻게 든 문제가 발생하여 무슨 일이 일어나고 있는지 읽을 수있는 코드를 얻습니다 ... 이봐. 그리고 마지막으로 소스에서 버그를 찾아서 고치십시오. 이제이 코드는 실제로 코드입니다. 수정을 위해 신중하게 읽어 보더라도 문서라고하는 것은 아닙니다.}

를 들어 '샘플' 가 제공하려고, 읽기 - 수정되지 구분이 매우 중요 끌 수 있습니다.

문서화 된 참조 환경에서 변경없이 실행될 때 일부 샘플이 실패하면 버그입니다. 문서의 버그입니다.이 버그는 수정하여 수정해야합니다.

이제 수정 된 샘플 또는 환경에 문제가있는 경우 더 이상 귀하의 잘못이 아닙니다. 문서를 수정하기위한 것이 아니므로 문서에 버그가 없음을 의미합니다. 그러한 경우 사용자에게 제공하는 데 도움이되는 것은 버그 수정이 아닌 지원 범주에 속합니다.

"어떻게해야합니까 ..."라는 질문에 답하는 것은 문서입니다.

개발자의 경우 요구 사항 사양 ( "어떻게 작성해야하는지"), 디자인 문서 ( "요구 사항을 어떻게 처리합니까"), 추적 성 매트릭스 ( "설계가 내 모든 요구 사항을 해결한다는 것을 어떻게 알 수 있습니까 "), 테스트 계획 ( "나는 내 코드가 작동 아는 방법"), 단위 테스트를 ( "나는 safisfied 요구 사항 X했습니다 아는 방법"), 어떻게 내가 내가 쓴 이유를 확인 다음 가난한 schlub 이해해야합니까 인라인 주석 ( " 이 way "), 배포 지침 ("설치를 위해이 제품을 어떻게 패키지합니까? "등)

즉, 사용자 매뉴얼 ( "소프트웨어 사용 방법"), 자습서 ( "이 특정 기능 사용 방법"), 릴리스 정보 ( "고정 된 버그 / 새로운 버그 기능이 무엇인지 어떻게 알 수 있습니까?"를 의미합니다. 추가 ") 등