오류 메시지에 관련 문서에 대한 링크를 포함 하시겠습니까?

외부 개발자가 사용하는 상용 라이브러리 및 코드 예제를 만듭니다. 라이브러리 사용 방법을 광범위하게 설명하는 문서 (등록 된 사용자에게 제공)가 있습니다.

많은 개발자가 처음 사용자이므로 많은 기본적인 오류가 발생합니다.

오류 로그에 문서에 대한 링크를 포함시키는 것이 적절합니까? 가능한 단점은 무엇입니까? 몇 가지 예견 할 수 있지만 다음을 극복하는 것이 가능해 보입니다.

• 오래된 문서 URL
• 최신 설명서에 반영되지 않은 버전 별 오류
• 다른 문제가 있습니다. 개발자에게 관련없는 문서를 보내 개발자의 시간을 낭비하고 있습니다.

내가 의미하는 바의 예에서 굵은 글씨를 추가하는 것이 좋은 생각입니까?

[오류] 프로젝트 독립형 -pom에서 목표 org.apache.maven.plugins : maven-archetype-plugin : 1.2.3 : generate (default-cli)를 실행하지 못했습니다 : 원하는 아키 타입이 존재하지 않습니다 (com.example.library). archetypes : library-archetype-blank : 1.2.3.0) -> 자세한 정보 및 가능한 문제 해결 은 http://example.com/docs/setting-up-an-archetype 을 참조하십시오

에 따르면 이러한 오류 메시지 지침 , 내 경험, 사람들은 문서 또는 도움말을 확인한하지 않음으로써 시간을 절약하고 싶다. 인터넷 검색도 오류를 넘어 설 수 있으므로 클릭해야 할 이유가있을 때 링크를 포함하십시오.

마지막으로, 당신은 아마 Nielsen의 최초의 컴퓨터 문서 법칙을 알고있을 것입니다 : 사람들은 그것을 읽지 않습니다. 이 발견은 사용자가 자신의 작업에 필수적이지 않은 판독 값에서 진정으로 수줍어하는 웹 사이트에서 더욱 강력합니다. 도움말을 클릭 하시겠습니까? 못.

사용자는 문제가있을 때만 시스템 설명서를 읽습니다 (제 2 법칙). 오류에서 복구하려는 경우 특히주의해야합니다. 이 경우 오류 메시지를 교육 리소스로 사용하여 사용자에게 소량의 지식을 제공 할 수 있습니다. 물론 모든 웹 컨텐츠와 마찬가지로 오류 메시지는 간단하고 요점이어야합니다. 그러나 오류 메시지는 여전히 시스템 작동 방식에 대해 사용자에게 조금 알려주고 더 잘 사용하는 데 필요한 정보를 제공 할 수 있습니다. 이를 위해 웹 기반 기술은 또 다른 지침을 가능하게합니다.

하이퍼 텍스트 링크를 사용하면 추가 배경 자료 나 문제에 대한 설명이 포함 된 간결한 오류 메시지를 페이지에 연결할 수 있습니다. (그러나 이것을 과도하게 사용하지 마십시오.)

네 가장 확실하지만

• 링크 썩음 은 문제가 될 것입니다. 이상적으로 알려진 대상 문서에서 동적으로 링크를 생성하지만 어떤 형태의 구성에서 접두사를 가져옵니다. 서버가 변경되면이 구성 요소를 업데이트하여 이전 코드를 유효하게 유지할 수 있습니다. 이 접두어 구성을 변경하여 문서를 로컬에서 사용할 수도 있습니다.
• 버전 관리 : 같은 방식으로 링크에 버전 정보를 포함 할 수있는 경우 링크가 항상 올바른 버전의 문서를 가리 키도록합니다.
• 문서를 편집 가능하게 만들기 실수를 동적으로 수정할 수있는 문서를위한 위키 유형의 사이트와 같은 것, 이상적으로는 사용자가 페이지에서 직접 주석을 달 수 있도록하는 것이 이상적입니다. 이를 통해 사용자가 참여하고 필요한 것을 쉽게 찾을 수 있으며 문서를 양호한 작업 상태로 유지하기 위해 황금 정보를 얻을 수 있지만 정기적으로 모니터링해야 하며 대부분 적극적으로 참여 해야합니다 .
• 생성 된 템플리트 는 빌드 시스템이 코드의 주석에서 문서의 기본 템플리트를 직접 생성하도록합니다. 간단하게 유지하지만 모든 링크가 항상 유효한 문서를 가리 키도록합니다. 위키를 사용하는 경우 이러한 템플릿을 쉽게 푸시 할 수 있는지 확인하고 코드와 동일한 방식으로 설명서 사이트를 홍보 할 수 있어야합니다 (prod 사이트와 다른 dev 사이트를 사용하고 코드를 prod로 홍보) prod 사이트에서 인서트를 자동으로 수행하십시오).

Java 또는 .NET으로 개발하는 경우 doc은 jar 파일 또는 DLL 파일에 포함될 수 있으며 접 두부를 변경하여 코드가 대신 로컬로 가져올 수 있습니다.

Wiki 접근 방식을 선택하는 경우 DokuWiki 는 단순함과 플랫 텍스트 파일을 기반으로 빌드 시스템에서 자동 주입에 매우 친숙해 지기 때문에 따뜻하게 권장 합니다. 즉, 귀하의 환경이나 고객에 대해 이것이 YMMV에 적합한 지 실제로 알지 못합니다.

내가 만든 가장 성공적인 도구 중 일부는 오류 메시지가 작업을 수행 할 가능성이 높은 실제 사용자를 대상으로하는 비슷한 접근 방식을 취했습니다. 즉, 오류가 적절한 추상화 수준에 있는지 확인하기 위해 많은 예외 포착 및 줄 바꿈을 수행해야했습니다. 또한 각 오류 메시지에 가장 가능성이 높은 오류 원인이 포함되어 있는지 확인하고 "xxxx 구성 값을 설정하지 않았습니까?" 오류가 발생한 컨텍스트에서 XXX 및 기타 항목이 생성되는 위치

이 접근 방식은 다소 단순하지만 제한적입니다. 그러나 링크 썩음이 필요하지 않은 경우에는 항상 문서가 있어야한다는 장점이있었습니다.

당신의 접근 방식은 다음 진화입니다. 훨씬 더 복잡하지만 훨씬 더 많은 잠재적 수익이 있습니다. 그러나 비용이 많이 들지만 올바르게 수행하면 쉽게 보상받을 수 있습니다.

온라인이 아닌 라이브러리와 함께 제공되는 오프라인 문서를 가리키는 것이 좋습니다.

(com.example.library.archetypes : library-archetype-blank : 1.2.3.0)-> 자세한 정보 및 가능한 문제 해결은 /usr/share/myprog-3.8.1/docs/setting-up-an-archetype을 참조하십시오

(분명히 Windows 라이브러리 인 경우 경로가 다를 수 있습니다).

여기에 장점이 있습니다 :

• 이런 식으로 문서는 항상 라이브러리와 동기화됩니다. 사람들은 오래된 라이브러리 버전으로 개발하고 문제를 해결합니다. 회사에서 이름을 변경하거나 제품 이름을 변경하거나 누군가가 갱신 할 때 공을 떨어 뜨릴 수 있습니다 example.com.

• 웹은 빠르게 변합니다. 귀하가 제공하는 링크 http는 몇 년 안에 주요 브라우저 만 지원할 것 https입니다. 아니면 우리 모두 gopher프로토콜 로 돌아갈 수 있습니다.

• 인터넷에 액세스하거나 최소한 도메인에 직접 액세스 할 수있는 환경에서 응용 프로그램 문제 해결이 항상 발생하는 것은 아닙니다.

• 당신은 당신의 문서가 "인증"벽 뒤에 있다고 언급합니다. 오류 메시지를 이해하기 위해 웹 사이트에서 계정을 만들어야하는 것은 쾌적하지 않습니다 (SO가 사람들이 로그인하지 않아도되는 이유).

이 문제에 접근 할 수있는 성공적인 방법이 있습니다. 메시지와 결합 된 예외가 고유한지 확인하여 웹 검색에 붙여 넣으면 정확하게이 문제와 관련된 모든 게시물을 쉽게 찾을 수 있습니다.

이것이 널 포인터 예외를 너무 싫어하는 비밀 이유입니다. 물론 우리가 null을 확인해야한다는 것을 싫어 하지만 가장 귀찮게하는 것은 하나를 실행할 때 검색 해야하는 유일한 고유 식별자는 휘발성 줄 번호라는 것입니다.

네, 이것들을 검색하고 싶습니다. 물론, 무언가가 null로 남겨 져서 사용되어서 일어난 일임을 알고 있습니다. 왜 즉각적으로 명백하지 않은 것은 왜 무언가가 널로 남겨 졌는가입니다.

따라서 다른 모든 문서 솔루션을 고려하십시오. 그러나 당신이 할 수있는 가장 게으른 일은 나에게 가장 좋은 일을 할 수 있습니다.

예쁘세요?