원본 문서: 프로그래머가 무시할 수 있는 열 가지

대다수의 원본 항목의 문서들은 모두 실망스럽기 때문에, 주로 아래의 몇 가지 방면에서 구현된다.

1. 좋은 자술이나 소개가 부족하다

자술은 잠재적인 사용자가 너의 프로젝트에 대한 첫인상이다.

만약 항목이 GitHub 에서 자동으로 이 항목의 홈페이지에 표시됩니다.

만약 네가 자술에 주의를 기울이지 않는다면, 이 잠재된 사용자들은 다시는 돌아오지 않을 수도 있다.

그래서 당신의 프로젝트는 사용자가 당신의 프로젝트에 관심을 가져야 합니다.

자술파일은 적어도 다음 몇 가지 설명을 포함해야 합니다:

● 어떤 항목?

● 어떤 사용자를 향한다;

● 어떤 하드웨어나 플랫폼에서 실행

● 주요 의존관계

● 어떻게 설치하거나 깊이 들어가는 방향 지침.

이것들은 지금까지 당신의 프로젝트를 들어 본 적이 없기 때문에 당신의 프로젝트를 영원히 고려하지 않을 수도 있습니다.

물론 당신이 자술하는 사용자가 무엇인지 알지만 필요할 때 약간의 주해와 유용한 링크를 덧붙여 사용자가 당신의 프로젝트를 이해하기 편리하다.

2. 온라인 문서를 제공하지 않기

이 분야에 대한 연구조사는 보지 못했지만 90%의 문서는 구글이나 인터넷의 다른 브라우저로 찾아온 것으로 생각한다.

그래서 문서는 반드시 온라인 및 사용할 수 있습니다.

이 점은 내가 어떻게 발견했을까? 많은 사용자들이 흔히 문제의 해답을 보지 않기 때문에 인터넷 검색 문제의 답에 직접적으로 문제가 발생한다.

따라서 온라인 문서를 제공하면 사용자가 더 좋은 문제를 해결할 수 있다.

3. 온라인 문서만

이 문제의 또 다른 부분은 개발자들이 온라인 문서만을 제공하는 것이다.

어떤 항목은 이 항목을 서로 교환할 수 있는 문서나 포함된 문서는 부합되지 않습니다.

예를 들어 PHP 언어는 문서를 첨부하지 않습니다. 문서를 원하면 단독 페이지로 열어야 합니다.

하지만 더 엉망인 것은 핵심 코드만 다운로드할 수 있다는 것이다.

이렇게 하면 사용자가 자신에 대한 유용한 정보를 얻을 수 없을 것이다.

개원 항목은 사용자가 인터넷을 방문할 때 그들은 온라인 문서를 필요로 한다고 생각할 수 없다.

물론 사용자가 당신의 프로젝트 사이트에 지나치게 의존하기를 바라지 않습니다.

4. 설치 문서를 포함하지 않기

이 문제는 통상 가방의 창조자가 프로젝트의 개발자가 아닌 문제다.

예컨대 Ubuntu Linux 운영체제에서 Perl 언어가 선택한 가방 자체는 단독 문서입니다.

사용자는 그가 설치할 때 필요한 문서와 핵심 언어를 설치하는 문서를 알아야 한다. 이러한 사용자가 문제를 만날 때 제때에 해결해야 한다.

5. 캡처 부족

잠재자 주의를 얻거나 소프트웨어의 올바른 사용법을 설명하는 것이 더 좋은 방법입니까? 현명한 방법은 캡처입니다.

인터넷 시대에 한 장의 그림은 아마도 수많은 말보다 낫다.

캡처는 사용자가 자신이 사용하는 방법이 옳은지를 판단할 수 있고, 자신이 잘못한 곳을 찾기 쉽다.

그래서 필요한 캡처는 원본 문서에 대해서도 중요하다.

6. 실례가 부족하다

코드 기반 사업에 대한 모의의 캡처는 물론 좋지만 관련 사례도 적어서는 안 된다.

이런 사례들은 추상적이어야 하지 않고 현실 세계에서 추출해야 한다.

일부 항목과 관련된 사례를 생성하여 사용자에게 소프트웨어 사용 과정 중 문제를 어떻게 해결할 것인지를 보여 준다.

초링크가 있다면 문서에 사용되는 것을 기억합니다.

사용자가 문서를 읽으면 이해할 수 있다고 생각하지 말고 문서에 일부 사용자가 이해할 수 없는 것이 있을 것이다.

이럴 때 당신의 모든 하이퍼링크 및 인용으로 사용자가 문제를 해결할 수 있도록 도와야 합니다.

8. 새 사용자 잊기

당신이 문서를 쓸 때, 당신은 개발자 자신의 각도에 서서 작성한 것이며, 이것은 소프트웨어의 개발자에게는 매우 쉽다.

그러나 새로운 사용자들에게 입문 문서가 필요하다.

새로운 사용자가 당신의 소프트웨어를 빨리 이해하거나 소프트웨어를 숙련시키기 위해서, 나는 개인적인 페이지를 사용하여 사용자에게 문문서를 써야 한다고 생각한다.

항목의 개발자는 반드시 사용자가 전체 항목에 대한 수요를 경청해야 한다.

가장 효과적인 방법은 더 많은 사람들이 너의 프로젝트를 시험적으로 사용해서 문제를 찾아내는 것이다.

동등한 것은 사용자 수요를 경청하는 과정에서 프로젝트 개발자는 사용자가 이런 문제를 제기하는 진정한 원인을 고려해야 한다는 것이다.

만약 당신의 항목에 충분한 사용자 그룹이 있다면, 사용자가 직접 문서에 평론을 첨가할 수 있습니다.

내가 본 가장 좋은 예는 PHP 언어입니다. 문서의 모든 페이지는 신분검증을 거친 사용자가 평론을 첨가하거나 첨가한 평론은 핵심 문서에 속하지 않습니다.