업계의 문서화에 대한 혐오감은 무엇입니까?

가장 기본적인 문서조차 작성하는 데 혐오감이 있습니다. 우리의 프로젝트 README는 상대적으로 적습니다. 문서에 업데이트 된 종속성 목록도 없습니다.

프로그래머가 문서 작성을 싫어하게 만드는 업계에서 알지 못하는 것이 있습니까? 필요한 경우 문서의 단락을 입력 할 수 있는데 다른 사람들이 왜 그렇게 반대합니까?

더 중요한 것은, 문서 작성이 미래에 시간과 좌절을 덜어 줄 것이라고 어떻게 확신 시키는가?

좋은 습관이라고 생각하는 것을 채택하지 않거나 나쁜 습관으로 보이는 것을 계속하고있는 사람들의 동기를 추측하는 것이 도움이되지 않는다고 생각합니다. 이 비즈니스에서 해당 범주 중 하나 또는 둘 모두에 해당 하는 사람들은 눈에 보이는 사람들보다 훨씬 많으므로 자신을 미치게하지 마십시오.

대신 문제와 가능한 해결 방법에 중점을 둡니다.

1. 좋은 문서를 직접 작성하십시오

팀의 모든 사람이 자신이 문제라고 생각하는 것에 노력을 기울일 것이라고 기대하는 것은 현실적이지 않을 수 있습니다. 팀에 비교적 새로운 사람이라면 더욱 그렇습니다. 팀의 창립 멤버 인 경우 이미이 문제를 이미 해결했을 것으로 보입니다.

대신 좋은 문서를 직접 작성하여 사람들이 사용하도록하는 목표를 향해 노력하십시오. 예를 들어, 팀의 누군가가 프로젝트 A의 소스 코드가 어디에 있는지 또는 프로젝트 A가 필요한 특별한 구성을 묻는다면 프로젝트 A 위키 페이지를 가리 킵니다.

누군가 C 클라이언트를 위해 커스터마이징하기 위해 Factory F의 새로운 구현을 작성하는 방법을 묻는다면 개발자 안내서의 10 페이지에 나와 있습니다.

대부분의 개발자는 문서를 읽는 것보다 훨씬 더 "코드를 읽을"수없는 것처럼 보이게 만드는 질문을 싫어하므로 이러한 특성에 대한 충분한 대답을 마치면 먼저 문서로 이동합니다.

2. 문서의 가치 입증

문서가 그 가치를 입증하는 곳 (또는 사용 된 경우)을 가리킬 수있는 기회를 갖도록하십시오. 미묘하게 행동하고 "내가 말했듯이"피하는 것은 좋지만

나중에 참조 할 수 있도록이 프로젝트의 위키 페이지에는 릴리스 2.1을 지속적으로 지원하기 위해 작성된 핵심 코드의 분기에 대한 정보가 있으므로 향후 릴리스 버전을 유지 관리하는 사람이 확인하는 경우 전체 회귀 테스트를 수행하지 않아도됩니다. 코드를 확인하기 전에 위키.

또는

작업 T를 수행하기위한 단계를 적어 두었습니다. 다른 사람이 사용하지 않더라도 실제로 신경 쓰지 않습니다. 이미 쓴 시간보다 더 많은 시간을 절약했습니다.

3. 선상 관리

문서화가 시간 / 돈을 절약 할 수있는 몇 가지 사건이 발생하면 문서화에 대한 뚜렷한 "해동"을 보게 될 것입니다. 이것은 예상 시간에 문서화 시간을 포함하여 요점을 누를 때입니다 (솔직히 말하면 컴파일 또는 체크인과 같은 긴 프로세스가 실행되는 동안 일반적으로 문서를 업데이트 / 생성합니다). 특히 이것이 최근 고용인이라면, 이것이 의문의 여지가 없지만 이전 직장에서 가져 오는 새로운 관행으로 간주 될 수 있습니다 (아마도 가능할 것입니다).

주의 말씀 : 대부분의 상사는 싫어 하기 때문에 이러한 지원은 위임의 형태로 될 것으로 기대하지 않습니다, 특히, 사람들은 아무것도 할 직접 청구 작업에 묶여 있지 것을. 대신, 더 많은 문서를 작성할 수있는 상대적으로 자유로운 고삐를 줄 가능성이 높습니다.

4. 문서를 볼 때 격려하십시오

사람들이 문서를 자주 쓰지 않는 이유 중 일부는 아무도 그것을 읽고 있지 않다고 생각하기 때문입니다. 그러므로, 당신이 좋아하는 것을 볼 때, 적어도 당신이 그것을 이용할 수 있다는 것이 기쁘다는 것을 언급하십시오.

팀에서 코드 검토를 수행하는 경우 좋은 의견을 장려하기 위해 미묘한 단어를 넣을 수 있습니다.

프레임 워크 G에 버그 B에 대한 해결 방법을 문서화 해 주셔서 감사합니다. 나는 그것에 대해 몰랐습니다.

팀에 실제로 문서화에 대해 열정적 인 사람이 있다면 , 점심이나 커피를 마시면서 그 사람을 키우고 팀의 나머지 부분을 볼 때 얻을 수있는 실망을 막기 위해 약간의 검증을 제공하는 것이 상처를 입지 않습니다. 문서를 중요하게 생각하지 않습니다.

그 외에도, 당신이 리드 또는 관리 직책에 있지 않으면 실제로 문제가 아닙니다. 말을 물로 인도 할 수는 있지만 마실 수는 없습니다. 그것이 당신의 말이 아니라면, 목이 말라서 기뻐할 수도 있지만, 여물통을 채우는 것만으로도 가능합니다.

내 경험에는 두 가지 주요 요소가 있습니다.

마감

대부분의 회사는 너무 오래되어 QA, 기술 부채 및 실제 디자인이 줄어 프로젝트 관리자가 나쁘지 않거나 지나치게 약속 된 고객 마감일을 맞출 수 있습니다. 기능적 품질까지 저하되는 환경에서는 문서와 같은 장기적인 투자가 거의 없습니다.

변화

개발자를위한 비교적 새로운 모범 사례는 주석을 강조하지 않는 것입니다. 아이디어는 두 곳 (코드 [테스트 포함]과 코드 주위의 주석)에 정보를 유지하면 거의 이익을 얻기 위해 정보를 동기화하는 데 많은 오버 헤드가 발생한다는 것입니다. "코드를 읽기가 어려워 주석이 필요한 경우 코드를 정리하는 데 시간이 더 걸리지 않습니까?"

나는 개인적으로 더 이상 의견을 보지 않을 것입니다. 코드는 거짓말을 할 수 없습니다.

문서는 동일한 맥락을 따릅니다. 민첩성이 널리 보급됨에 따라 사람들은 요구 사항이 정기적으로 변한다는 것을 인정합니다. 리팩토링이 널리 사용됨에 따라 코드 구성이 상당히 바뀌게됩니다. 변화해야 할 모든 것들을 문서화하는 데 왜 시간을 소비합니까? 코드와 테스트는 그 일을 충분히 수행해야합니다.

여기에는 여러 가지 요인이 있습니다.

1. 잘 작성된 코드는 자체 문서입니다. 다른 모든 것들이 동일하다면 더 많은 문서가 아닌 자체적으로 명확한 코드를 작성하는 것이 좋습니다. 그렇게하면 해당 코드를 변경할 때 적은 문서를 수정해야합니다.

2. 문서 작성은 코드 작성과 다른 기술 일 것입니다. 일부 소프트웨어 개발자는 다른 소프트웨어보다 우수합니다. 일부는 문서를 작성하는 것보다 코드를 작성하는 것이 훨씬 좋습니다.

3. 문서는 두 번 이 아니라 한 번만 작성해야합니다 (소스 코드에서 한 번, 프로그래머 안내서에서 다시 한 번). 그렇기 때문에 XML 주석 및 문서 생성기와 같은 것이 있습니다. 불행히도 이러한 도구를 사용하는 것은 문서를 직접 작성하는 것보다 더 까다 롭고 번거로울 수 있으므로 이러한 도구가 널리 사용되지 않는 이유가 있습니다.

4. 좋은 문서는 시간이 많이 걸리고 잘하기 어렵다. 다른 모든 것들이 동일하다면 이미 존재하는 코드에 대한 문서를 작성하는 것보다 새로운 코드를 작성하는 것이 더 가치가있을 수 있습니다.

5. 코드가 변경되면 설명서도 변경해야합니다. 문서가 적을수록 변경해야 할 문서가 적습니다.

6. 어쨌든 아무도 문서를 읽지 않아 왜 귀찮게합니까?

방에있는 코끼리 : 프로그래머는 (필요하게) 작가가 아니다. 또한 그들이 기술 구현 자들에게 그들의 구현을 구체화 할 필요도 없다. 방 안에있는 두 번째 코끼리 : 테크니컬 라이터는 일반적으로 미래 개발자에게 유용한 세부 정보를 제공 할 수 없습니다 (개발자가 설명 할 경우에도).

적절한 문서가 없으면 복잡한 시스템이 시간이 지남에 따라 거의 뒤죽박죽이 될 수 있습니다. 코드는 그 정확성에 반비례 적으로 가치가 떨어진다 [sic]. 해결 된 경영진은 개발자로부터 코드 및 동축 정보를 읽을 수있는 소프트웨어 엔지니어를 고용하여 개발자 요금으로 지불하고 문서화 및 문서화를 요구합니다. 이 작가는 코드를 읽을 수 있으며 어떤 질문을해야하는지 알고 필요할 때 세부 사항을 채울 것입니다. QA 부서와 마찬가지로 내부 문서 부서도 있습니다.

코드를 이해하기 쉽기 때문에 제 3 자에게 라이센스를 부여 할 수 있고 코드를보다 쉽게 ​​감사 및 개선 / 리팩토링 할 수 있으므로 코드를 더욱 유용하게 사용할 수 있습니다. 더 가벼운 버전의 소프트웨어를 제외하면 프로젝트에 새로운 개발자를 더 쉽게 소개 할 수 있으며 지원 엔지니어가 귀하를 위해 일하는 것을 좋아할 것입니다.

이것은 결코 일어나지 않을 것입니다.

더 중요한 것은, 문서 작성이 미래에 시간과 좌절을 덜어 줄 것이라고 어떻게 확신 시키는가?

그렇게합니까?

두 가지 유형의 문서가 있습니다.

유용한 문서

완성 된 제품, API, 서버의 IP 주소 또는 URL 이름 등을 사용하는 방법을 설명합니다. 기본적으로 매일 많이 사용되는 모든 항목을 설명합니다. 잘못된 정보는 빠르게 발견되어 수정 될 것입니다. 쉽고 쉽게 편집 할 수 있어야합니다 (예 : 온라인 위키).

쓸모없는 문서

자주 변경되는 문서로, 그 문서에 관심이있는 사람은 거의 없으며 어디에서 찾을 수 있는지 아무도 모릅니다. 구현중인 기능의 현재 상태와 같습니다. 또는 3 년 전에 업데이트 된 SVN 어딘가에 숨겨진 문서 doc의 요구 사항 문서. 이 문서를 작성하는 데 시간이 걸리고 나중에 잘못되었다는 것을 알기 위해 시간이 걸립니다. 이 유형의 문서에 의존 할 수 없습니다. 쓸모가 없습니다. 시간을 낭비합니다.

프로그래머는 쓸모없는 문서를 쓰거나 읽는 것을 좋아하지 않습니다. 그러나 당신이 그들에게 유용한 문서를 보여줄 수 있다면, 그들은 그것을 쓸 것입니다. 우리는 자주 필요한 정보를 모두 쓸 수있는 Wiki를 소개 할 때 마지막 프로젝트에서 성공을 거두었습니다.

주된 이유는 의지가 부족하고 문서 기능에 대한 이해가 부족하기 때문입니다. 고려해야 할 여러 종류의 문서가 있습니다.

제품 / 릴리스 문서

이것은 '완성 된'제품과 함께 나오는 모든 것입니다. 이것은 단순한 매뉴얼이 아니라 README, 변경 로그, 하우투 등입니다. 이론적으로는 작성하지 않아도되지만 사람들이 사용하지 않는 제품이나 불필요하게 비싼 지원 부담이 생길 수 있습니다.

API 설명서

이것은 상대적으로 정적 인 것이어야합니다 . 수많은 소비자가 API를 코딩하고있을 수 있으므로 API를 사용하는 방법을 설명하는 산문이 가치가있을 정도로 충분히 안정적이어야합니다. 매개 변수가 지원되는 기술, 반환 값이 될 수 있습니다 무엇 무엇을 다른 사용자에게 추상화의 오른쪽 수준에서 API를 이해하는 능력 수 던져 질 수있는 오류 - 인터페이스 ( 하지 구현).

코드 주석

의견에 대한 업계 의견은 현재 유동적 인 것으로 보입니다. 내가 전문적으로 코딩을 시작했을 때, 주석은 코드 작성과 관련하여 사인 이었다 . 이제 패션은 매우 명확한 코드를 작성하는 것입니다. 주석은 필요하지 않습니다. 많은 현대 언어가 훨씬 더 높은 수준으로 작성되고 어셈블러보다 Java, JavaScript, Ruby 등에서 읽을 수있는 코드를 작성하는 것이 더 쉽기 때문에 이것이 부분적으로 추측 될 수 있습니다. , C, FORTRAN 등. 따라서 주석의 값이 훨씬 큽니다.

나는 여전히 코드 섹션의 의도 또는 특정 알고리즘이 왜 더 명백한 알고리즘을 통해 선택되었는지에 대한 세부 사항 을 설명하는 의견에 가치가 있다고 생각합니다 ( '고정'코드에서 지나치게 열성적인 리팩터링을 피하기 위해 ' 실제로 수정해야합니다).

불행히도, 프로그래머의 문서화 결정에 관련된 이기심, 합리화 및 자기 망상이 많이 있습니다. 실제로 코드와 마찬가지로 문서의 주요 대상은 다른 사람들입니다. 따라서 어떤 수준에서든 문서 작성 (또는 작성하지 않음)에 대한 결정은 팀 수준에서 내려야합니다. 추상화 수준이 높을수록 개발자 이외의 사람이 수행하는 것이 더 합리적 일 수 있습니다. 의견 수준의 문서에 관해서는 의견의 목적과 의도에 대한 합의에 도달하는 것이 특히 혼합 된 능력 및 경험 팀에서 함께 합의되어야한다. 선임 개발자가 후배 개발자가 접근 할 수없는 코드를 작성하는 것은 좋지 않습니다. 잘 배치되고 잘 작성된 문서는 팀이 훨씬 더 효과적으로 운영 할 수있게합니다.

여기 내 센트가 있습니다.

1. 애자일 선언문은 "포괄적 인 문서에 대한 소프트웨어 작업"이라고 말하고 모든 사람들이 "오른쪽 항목에는 가치가 있지만 왼쪽에있는 항목은 더 중요하게 생각합니다."

2. 슬프게도 https://en.wikipedia.org/wiki/Code_and_fix 에서 일반적 이며 설명서는이 모델에서 작동하지 않습니다 (동기화됩니다).

3. 소프트웨어 개발 산업은 잘 규제되지 않습니다. 문서를 작성하기위한 법적 요구 사항은 없습니다.

4. 자체 문서화 코드가 현재 추세입니다.

그렇게 말하면, 거기에 좋은 문서가 많이 있다고 생각합니다.

문서화에는 시간이 걸리고, 많은 개발자들이 쓸모없는 것보다 더 나쁜 문서를 가지고 너무 많은 문제를 겪고 있다고 생각합니다. 그들은 문서화를 통해 관리자 (일정표의 QA 부분을 계속 유지하는 사람)로부터 문제를 해결할 수있을뿐 아니라이를 포함하여 다른 사람에게 도움이되지 않는다는 아이디어를 얻습니다.

반 정도의 문서는 미래에 대한 투자입니다. 미래에 신경 쓰지 않는다면 (다음 급여 이상으로 생각하지 않거나 문제가 될 것이라고 생각하지 않기 때문에) 문서 작성에 대한 생각은 매우 고통 스럽습니다.

다른 많은 응답은 적어도 두 가지 유형의 문서가 있다는 점에 반합니다. 하나는 다른 개발자 용이고 다른 하나는 최종 사용자 용입니다. 환경에 따라 시스템 관리자, 설치 관리자 및 헬프 데스크 직원을위한 추가 설명서가 필요할 수도 있습니다. 대상 고객마다 요구 사항과 이해 수준이 다릅니다.

(입체적) 전형적인 개발자를 고려하십시오. 그는 선택하는 코더입니다. 그는 대중의 눈에서 경력을 선택했으며 주로 자신과 의사 소통을하는 키보드 뒤에 오랜 시간을 보냅니다. 문서화 과정은 의사 소통의 한 형태이며 좋은 문서를 작성하는 데 필요한 기술은 좋은 코드를 작성하는 데 필요한 기술과 모순되지 않습니다.

훌륭한 문서 작성자는 사용자 언어, 관리 언어, 지원 직원 언어, 개발자 언어 등 여러 언어로 통신 할 수 있습니다. 코더가 통신하는 내용을 이해하고이를 다른 모든 그룹이 이해할 수있는 형식으로 변환하는 것은 문서 작성기의 작업입니다.

코더가 훌륭한 의사 소통자가되기 위해 필요한 기술을 개발할 것으로 기대할 때 (필기 또는 기타) 기본 기술 세트 (코딩!)를 연마하는 데 소요되는 시간이 줄어 듭니다. 컴포트 존에서 멀어 질수록 (다른 코더와의 코딩 및 통신) 작업을 잘 수행하는 데 더 많은 시간과 에너지가 필요합니다. 전문 코더가 자신의 핵심 역량에 중점을두기를 원할 것으로 합리적으로 기대할 수 있습니다.

따라서 인라인 코드 주석을 제외한 문서는 코더가 아닌 커뮤니케이터에게 맡기는 것이 가장 좋습니다.

코드를 읽으면 작동 방식을 보여줍니다 . 이유를 설명 할 수 없습니다 . 의견이 필요합니다.

코드를 읽으면 메소드 이름과 매개 변수 유형이 표시됩니다. 시맨틱이나 저자의 정확한 의도를 설명 할 수는 없습니다. 의견이 필요합니다.

주석은 코드 읽기를 대체하지 않으며 추가합니다.

코드 그대로 문서가 실행되지 않습니다. 결과적으로 문서가 제자리에 있고 완전한지 확인하기위한 효과적인 피드백 루프가없는 경우가 종종 있습니다. 이것은 코드 주석이 썩는 경향이있는 동일한 이유입니다.

Donald Knuth는 Literate Programming 을 소프트웨어의 품질을 향상시키고 코드로 효과적으로 문서를 작성하는 방법으로 홍보했습니다 . 이 접근 방식을 매우 효과적으로 사용한 몇 가지 프로젝트를 보았습니다.

개인적으로 코드의 공개 API를 가능한 한 읽기 쉽게 유지하고 단위 테스트를 사용하여 다른 개발자의 사용을 문서화하려는 현대적인 추세를 고수하려고합니다. 이것이 API를 탐색하고 발견 할 수있는 형태로 만드는 더 큰 아이디어의 일부라고 생각합니다. 이 접근법은 HATEOAS 가 웹 서비스로 달성 하려는 것의 일부라고 생각 합니다.

사소한 점이지만 명백히 적은 양의 문서를 작성하는 일부 개발자에게는 중요한 것 같습니다. 입력 할 수 없습니다. 10 개의 손가락 시스템에 대한 근사치가 있다면 쉽게하기 때문에 더 많은 문서를 작성하는 경향이 있습니다. 그러나 사냥과 펙킹에 갇혀 있으면 길을 잃습니다. 내가 채용에 책임이 있다면 실제로 확인할 것입니다.

문서 읽기를 싫어하는 사람들은 문서 쓰기를 싫어합니다. 많은 프로그래머들이 문서를 철저히 읽지 않도록 최선을 다할 것입니다.

작문에 집중하지 말고 독서에 집중하십시오. 프로그래머가 문서를 읽고 그로부터 내용을 동화하면 그 가치를보고 일부를 작성하려는 경향이 훨씬 커집니다.

현재 작업을 시작하고 이전에 작업했던 사람들로부터 하드웨어 + 소프트웨어 프로젝트를 인수했을 때 시스템을 설명하는 수백 페이지 정도의 MS 워드 문서가 제공되었습니다. 생산하는 데 며칠이 걸렸습니다. 나는 아마 두 번 그것을 보았다. 거기에 방대한 양의 정보가 있었음에도 불구하고 시스템에 대한 실제 질문에 거의 대답하지 않았으며, 심지어 그럴 때에도 코드를 보는 것이 더 빠릅니다.

그런 경험이 충분하다면, 왜 생각하기 시작합니까? 사람들이 묻지 않은 질문에 대답하는 데 왜 시간을 보내십니까? 사람들이 문서에서 어떤 정보를 찾을 것인지 예측하는 것이 얼마나 어려운지를 깨닫기 시작합니다. 그것은 쓸모없고, 불분명하거나 명백하며, 가장 시급한 질문에 대한 답이 결여되어있는 사실들로 필연적으로 가득 차 있습니다. 유용한 문서를 작성하는 것은 사람의 행동을 예측하는 노력입니다. 테스트 및 디버깅을 여러 번 반복하기 전에 사용자 인터페이스 디자인이 성공하지 못할 것처럼 사람들이 시스템을 어떻게 해석 할 것인지에 대한 기대에 기초하여 유용한 문서를 작성할 수 있다고 생각하는 것은 순진합니다. 문서와 그 언어가 그 해석에서 역할을합니다.

나는 문서를 작성해야하는 압력의 대부분이 불쾌한 집안일이라는 사실과 사람들이 서로 불쾌한 집안일을하는 것을 좋아한다는 사실에서 비롯된다고 생각하는 경향이있다 ( "여러분은 필지 스터지를 먹지 않았습니다!").

하나

나는 문서가 모든면에서 절망적이라고 생각하지 않는다. 나는 사람들이 일을 마치기 전에 해결해야 할이 추가 부담, 서두르는 마지막 정리 작업 및 확인해야 할 상자로 문서를 볼 때 주로 희망이 없다고 생각합니다. 문서화는 항상 당신이 항상하는 일상의 측면으로 작업해야하는 것입니다. 전자 메일은 특히 문서를 작성하는 좋은 방법이라고 생각합니다. 새로운 기능을 추가 할 때 몇 사람에게 기능을 알려주는 빠른 이메일을 작성하십시오. 새로운 회로도를 그릴 때 PDF를 생성하여 관심있는 사람에게 보내십시오. 이메일의 장점은 다음과 같습니다.

1. 사람들은 일반적으로 이메일을 확인하지만 "doc"라는 폴더를 가로 지르는 사람은 없습니다.

2. 전자 메일은 해당 기능 및 관련 기능과 그 당시 진행중인 다른 모든 문제를 논의하는 다른 전자 메일로 둘러 싸여 있습니다.

3. 이메일은 짧고 집중적이며 제목이 있습니다.

4. 이메일을 통해 관심있는 사람들은 즉시 질문을 할 수 있습니다.

5. 사람들은 모든 것을 위해 메일을 사용하고 메일 클라이언트는 수년에 걸쳐 상당히 발전했기 때문에 전자 메일은 검색 가능성이 높습니다.

6. 이메일에있는 경우 다른 사람이 이메일을 찾을 수있는 위치를 알고 있습니다.

이론적으로 코드의 주석은 "항상 어쨌든 항상하는 하루의 관점"이어야하지만 솔직히 말하면 코드에서 주석을 읽지 않습니다. 이유가 확실하지 않지만 이메일이 해결되는 컨텍스트가 부족하기 때문에 그다지 도움이되지 않습니다.