첫 번째 소프트웨어 문서 작성 가이드

개발자로서 자부심과 기쁨은 코드입니다. 읽을 수 있고 건조 원칙을 충족하며 모범 사례를 반영하며 최종 제품은 대상 사용자에게 일종의 문제를 해결하는 훌륭한 도구입니다. 그러나 코드에 얼마나 많은 작업을했는지, 소프트웨어가 문서화가 없거나 문서를 나중에 고려하여 문서를 작성하고 중요하지 않은 것으로 취급하는 경우 사용자는 이와 협력하는 데 거의 기쁨이 없을 것입니다. 결국 다른 사용자 친화적 인 제품을 선택하십시오 이 기사에서는 첫 번째 소프트웨어 문서를 작성하여 실행할 수있는 여러 가지 실용적인 안내 원칙을 찾을 수 있습니다. 키 테이크 아웃

우수한 소프트웨어 문서는 사용자 채택 및 이해에 중요하며 개발자와 사용자 간의 커뮤니케이션 도구 역할을합니다. 튜토리얼, 방법 안내서, 참조 안내서 및 설명이 포함되어 있어야하며 소프트웨어 기능에 대한 포괄적 인 안내서를 제공해야합니다. 문서의 대상 고객은 사용 된 내용과 언어를 형성하므로 명확하게 식별해야합니다. 이 안내서의 맥락에서, 사용자 매뉴얼이나 프로젝트 문서보다는 소프트웨어에 대한 다양한 친숙 함을 개발하는 개발자를위한 문서에 중점을 둡니다. 문서는 쉽게 발견 할 수 있고, 잘 구조적이며, 정기적으로 업데이트되어야합니다. 코드 업데이트가 발생함에 따라 관련성 있고 정확한 상태를 유지하기 위해 소스 컨트롤에서 문서를 코드에 가깝게 유지하는 것이 좋습니다. FAQ 페이지를 포함 시키면 일반적인 사용자 쿼리를 해결하는 데 도움이 될 수 있습니다.

기존 문서를 넘어서 블로그 게시물은 소프트웨어 기능을 설명하고 자습서 제공 및 업데이트를 공유하는 데 유용한 도구 역할을 할 수 있습니다. 이것은 소프트웨어 주변의 커뮤니티를 장려하여 성장과 성공에 기여할 수 있습니다. 좋은 문서화 관행의 예는 Greensock, React 및 Vue.js.

문서가 중요한 이유 소프트웨어와 관련하여 Mike Pope는 다음과 같이 말하는 적절한 말을합니다. 문서화되지 않으면 존재하지 않으면

. > 왜 그런가요? 글쎄, 개인적인 경험을 예로 들기 위해, 나는 새로운 JavaScript 애니메이션 라이브러리를 찾고있는 웹을 탐색하고 있었고, 내가 정말로 좋아하는 기능에 대한 설명을 가지고 나왔습니다. 그러나 문서가없고 시작 섹션이 아니라 설명이나 예제가 거의없는 베어 본 API 페이지 만있었습니다. 내가 그 라이브러리를 사용했다고 생각하십니까? 물론, 나는 그렇지 않았습니다. 나는 그것에 너무 좌절하여 나에게 더 의미가있는 무언가로 옮겼습니다.

의 문제에 대한 좋은 JavaScript 라이브러리가 실패한 이유 , Nicholos Zakas는 다음과 같은 답변을 제공합니다.

문서의 부족 . 도서관이 아무리 훌륭하고 디자인이 얼마나 지능적이든, 당신이 그것을 이해하는 유일한 사람이라면, 그것은 좋은 일을하지 않습니다. 문서화는자가 생성 된 API 참조뿐만 아니라 주석이 달린 예제 및 심층 자습서를 의미합니다. 라이브러리를 쉽게 채택 할 수 있도록 세 가지가 모두 필요합니다. 소프트웨어 문서가 결정적으로 중요한 또 다른 중요한 이유는 그들이 현재 자아와 미래의 자아 사이의 커뮤니케이션 도구 역할을하고 현재 자신과 소프트웨어를 연구 할 수있는 다른 개발자 사이의 커뮤니케이션 도구 역할을하기 때문입니다. 읽기 가능하고 댓글을 달린 코드를 작성하더라도, 반드시 6 개월 안에 여전히 당신이 기능을 썼는지 또는 그 문제에 대한 다른 코드의 다른 부분 인 당신이했던 방식으로 여전히 당신에게 명확하지 않을 것이라는 의미는 아닙니다.

문서를 사용하면 코드 뒤에 를 전송할 수 있습니다. 같은 방식으로 코드 댓글은

가

가 아닌 이유를 설명합니다. 문서화는 동일한 목적을 제공합니다. - 문서 작성에 대한 초보자 안내서 확실히, 사람들이 코드를 사용하고 결국 코드를 ​​업데이트하고 개선 할 수 있기를 원합니다. 이것들은 모두 제품 뒤에 지원 커뮤니티의 성장에 기여하는 요소이며, 이는 견고성, 성숙도 및 성공을 얻는 데 중요합니다. . 소프트웨어와 함께 할 훌륭한 문서가 없다면이 모든 것을 달성하는 것은 어려울 것입니다. 누가 소프트웨어 문서는 입니다 무엇이든 쓸 때 청중이 누구인지 명확하게 확인하십시오. 문서는이 규칙에 예외가 아닙니다. 이렇게하면 청중이 직면 할 수있는 문제, 제품에 대한 친숙 함 또는 제품 사용에 대한 전제 조건에 대한 친숙 함을 명확하게 설명합니다. 이 정보는 컨텐츠와 사용하는 언어를 만드는 방식에 중요합니다. 두 가지 종류의 문서가 있습니다.이 기사는 다음과 관련이 없습니다.

사용자 설명서. 예를 들어, 언니는 자신의 블로그를 게시하기 위해 WordPress를 사용하기로 결정할 수 있습니다. 그녀는 개발자가 아니지만 DEV가 아닌 것이 WordPress와 함께 블로그를 시작하고 실행할 수 있다고 들었습니다. 이제 그녀는 서버에서 소프트웨어를 다운로드하고 구성하는 방법, 게시물 작성, 게시 및 업데이트 방법, 게시물에 이미지를 추가하는 방법 등에 대한 지침이 필요합니다. 다시 말해서, 그녀는 사용자가 필요합니다. 매뉴얼.
1. 프로젝트 문서. 이러한 종류의 컨텐츠는 프로젝트의 readme 파일로 갈 수 있지만 이러한 종류의 문서는 소프트웨어 자체보다 프로젝트와 더 관련이 있습니다. WordPress 예제를 계속하기 위해 WordPress로 많은 연습을 한 후 소프트웨어에 기능을 추가하거나 버그를 수정하기로 결정할 수 있습니다. 이 경우 변경 사항, 컨벤션 및 모범 사례, 기부 정책, 당면한 작업과 관련된 팀 토론에 참여하는 방법 등과 같은 것을 알아야합니다.
여기서 생각한 문서의 종류는 주로 소프트웨어에 익숙한 수준이 다른 개발자를 대상으로하고 프로젝트에서이를 사용해야합니다. 예를 들어, WordPress 테마를 작성하는 경우 시작 방법, 스타일 시트 및 JavaScript 문서를 포함하는 방법, 데이터베이스와 통신하여 게시물 등을 표시하는 방법을 알아야합니다. 문서에 포함시킬 내용 인기있는 접근 방식은 Tom Preston-Werner가 옹호하는 Readme Driven Development입니다. 코드 작성을 시작하기 전에 readme 문서를 작성하는 것으로 구성됩니다. 이 문서는 소프트웨어에 대한 소개이며 일반적으로 다음을 포함합니다.
2. 소프트웨어가하는 일에 대한 설명과 문제가 해결되는 문제
코드가 일반적으로 사용되는 상황을 보여주는 예

코드 및 버그 추적기 링크 faqs 및 지원을 요청하는 방법 소프트웨어를 설치하는 방법에 대한 지침 라이센스 정보

그러나 내 견해로는 소프트웨어/라이브러리를 사용하는 개발자가 실제로 고전적인 readme 파일을 넘어서도록 도울 수있는 견고한 문서를 가지고 있습니다. Daniele Procida에 이어 훌륭한 사용자 경험을 위해 문서 자료에 다음 항목을 포함시킬 것을 제안합니다. 튜토리얼 초보자는 소프트웨어 문서에서 튜토리얼을 찾는 것을 좋아할 것입니다. 튜토리얼은 사용자에게 소프트웨어를 사용하여 프로젝트를 완료하는 방법을 보여 주므로 소프트웨어를 사용하여 수행 할 수있는 일을 신속하게 얻을 수 있습니다.

튜토리얼은
• 레슨 입니다. 그들은 초보자에게 무언가를 달성 할 수 있음을 보여주기 위해 프로젝트가 필요로하는 것입니다. -
• Daniele Procida

방법 가이드 방법 안내서는 사용자가 소프트웨어를 사용하여 실제 작업을 해결할 수 있도록 도와줍니다. Procida는 사용자에게 특정 목표에 성공적으로 도달 할 수 있도록 사용자에게 제공하는 방향이라는 점에서 레시피와 비교합니다. 완전한 초보자를 목표로하는 튜토리얼과 달리 방법 안내서는 사용자가 이미 기능, 도구 및 간단한 작업을 수행하는 방법에 대한 몇 가지 기본 지식을 가지고 있다고 가정합니다. 참조 가이드 참조 안내서는 소프트웨어 코드 (기능, API 등)의 기술적 참조이며 소프트웨어 사용 방법에 대한 기본 설명을 제공합니다. 예를 들어, 특정 클래스를 인스턴스화하는 방법, 특정 방법을 호출하는 방법 등을 찾을 수 있습니다.

참조 안내서는

기계의 기술적 설명 입니다. - Daniele Procida

이것은 대부분의 프로젝트에서 찾을 수있는 문서입니다. 개발자는 코드와 사용 방법에 대한 모든 것을 알고 있기 때문에 글을 쓰는 데 매우 능숙합니다. 설명 설명은 소프트웨어에 대한 높은 수준의 이해와 관련이 있다고 생각되는 특정 주제에 대한 깊은 다이빙 또는 토론입니다. 설명에 대해 Procida는 다음을 지적합니다

이 문서 섹션은 명시 적으로 생성되지 않으며 대신 설명의 스 니펫이 다른 섹션들 사이에 흩어져 있습니다. 때로는 섹션이 존재하지만 배경 또는 기타 노트

와 같은 이름을 가지고 있으며 실제로 기능에 대한 정의를 수행하지 않습니다. 주제는 방법 가이드 또는 튜토리얼과 같이 사용자가 배우기를 원하는 특정 작업에 의해 정의되지 않습니다. 참조 자료와 같은 기계 조각에 의해 정의되지는 않습니다. 그것은

you 생각에 의해 정의되어 한 번에 다루기위한 합리적인 영역이므로 토론을위한 주제의 분할은 때때로 약간 임의적 일 수 있습니다. . 주의를 기울여야하는 것들 Docs를 사용자 친화적이고 관련성있게 만드는 데 유용한 포인터를 살펴 보겠습니다. 문서를 발견 할 수있게 만드십시오 소프트웨어 문서를 쉽게 찾을 수 있도록 작업을 수행하는 것이 좋습니다. 일부 SEO 기술을 일부 마케팅 전략과 함께 사용할 수 있으므로 가능한 많은 사용자가 그것을 붙잡을 수 있습니다.

또한, 문서에 넣은 내용은 특정 정보를 검색하는 구조로 구성되어야합니다. Steve Konves는 단일 연결된 트리에서 문서를 구조화 할 것을 권장합니다. 루트 노드에서 시작하여 모든 관심있는 사용자가 발견 할 수있는 명백한 위치에 배치해야합니다. 다른 모든 항목에 쉽게 액세스 할 수 있습니다. 프로젝트의 readme 파일은 트리 전체의 훌륭한 루트 노드로서 실제로 잘 작동하는 데 적합합니다.또한 소프트웨어 사용자로부터 도움 요청을 받으면 답을 작성하여 쉽게 액세스 할 수있는 FAQ 페이지에서 사용할 수있게 할 수 있습니다. 그렇게하면 사용자를 돕는 데 소비하는 시간이 줄어들지 만, 사용자에게 가장 자주 필요한 정보의 종류에 대한 명확한 아이디어를 제공하여 먼저 문서를 문서화하여 문서의 눈에 띄는 장소에 보관할 수 있습니다.

. 문서가 최신 상태이며 버그가 없도록하십시오 소프트웨어 문서에 쉽게 액세스하는 것이 좋지만 사용자가 해당 콘텐츠가 오래되지 않았거나 샘플 코드 또는 지침이 버기 결과로 이어지는 것을 알게되면 가장 실망 스럽습니다. 그럼에도 불구하고 Steve Konves는 소스 제어에서 문서를 코드에 가깝게 유지할 것을 제안합니다. 이런 식으로 개발자가 코드를 업데이트하면 문서 자료가 표시되어 문서를 업데이트하는 것이 훨씬 더 가능성이 높습니다.

. 또한 버그 발생을 최소화하려면 문서에서 제공하는 지침과 코드 샘플을 철저히 테스트합니다. 추가 팁과 몇 가지 인기있는 예 문서에서 멈추지 마십시오. 블로그 게시물은 소프트웨어와 그 기능을 광범위한 잠재적 사용자에게 알려주는 데 유용합니다. 블로그를 사용하여 제품이 수행하는 작업에 대한 설명을 제공하고 사용자 친화적 인 자습서, 팁 및 요령, 연습, 업데이트 설명 등을 제공합니다. 포럼 - 강력한 커뮤니티가 모여 성장할 수있는 주변.

내 관점 에서이 넓은 문서 아이디어의 훌륭한 예는 널리 성공적인 JS 애니메이션 플랫폼 인 Greensock에 의해 구현되며, 웹 사이트의 웹 사이트를 사용하기 쉽고 잘 사용하기 때문에 많은 것을 사용하고 있습니다. 구조화 된 문서, 슈퍼 유용한 포럼, 블로그 게시물, 빠른 팁 등. react and vue.js는 또한 훌륭한 예로 간주 될 수 있습니다. 해당 웹 사이트에 액세스하자마자 홈페이지는 빠른 태그 라인에서 각 라이브러리가 무엇을 제공하는지 알려주고, 왜 도서관이 프로젝트에 대한 훌륭한 선택으로 간주 될 수 있는지에 대한 자세한 내용을 알려줍니다. 두 웹 사이트 모두 부드러운 소개, 예시적인 스 니펫, 짧은 작업 초보자가 코드 놀이터 등을 사용하여 달성 할 수있는 부드러운 소개를 사용하여 덜 협박하기 시작합니다. 일단 사용자가 새로운 소프트웨어에 대해 약간의 자신감을 얻으면 더 기술적 인 API 문서를 쉽게 찾을 수 있습니다. 도움말을 얻는 방법을 자세히 설명하고, 생태계에 정보 표시, 뉴스 또는 블로그 섹션을 제공하는 등 JS 구역을 떠나 훌륭한 웹 사이트를 가진 인기있는 UI 라이브러리 필드로 들어가려면 부트 스트랩을 남길 수 없습니다. Bootstrap 웹 사이트에서는 라이브러리가 좋은 것과 신속하게 시작하는 방법뿐만 아니라 포괄적이고 잘 구조화 된 문서와 블로그를 통해 사용자가 새로운 기능을 업데이트 할 수 있습니다.

결론 좋은 문서 작성에는 문제가 있지만 사용자가 소프트웨어 기능을 구현하는 것이 얼마나 쉬운 지 생각하면 확실히 100 번을 지불합니다. 이로 인해 소프트웨어의 인기에 기여하여 매력적이며, 따라서 깊이 배우고 성장, 안정성 및 장기 기여에 기여하는 데 기꺼이 투자하려는 개발자 커뮤니티를 일으킬 가능성에 개방적입니다. 사용법.

소프트웨어 문서 작성에 대한 자주 묻는 질문 (FAQ) 소프트웨어 문서를 작성할 때 고려해야 할 핵심 요소는 무엇입니까?

소프트웨어 문서를 작성할 때 대상 고객, 문서의 목적 및 작성중인 문서 유형을 고려하는 것이 중요합니다. 사용 된 언어는 명확하고 간결하며 이해하기 쉬워야합니다. 문서는 논리적 인 정보 흐름으로 잘 구조화되어야합니다. 이해를 돕기 위해 필요한 경우 다이어그램이나 스크린 샷과 같은 비주얼을 포함하는 것도 중요합니다. 마지막으로, 정확성과 명확성을 위해 문서를 철저히 검토하고 편집하는지 확인하십시오.

소프트웨어 문서를 사용자 친화적으로 만드는 방법은 무엇입니까?

소프트웨어 문서를 사용자 친화적으로 만들려면 간단하게 사용하십시오. 그리고 명확한 언어. 가능한 한 전문 용어와 기술적 용어를 피하십시오. 사용해야하는 경우 명확한 정의를 제공하십시오. 콘텐츠를 논리적으로 구성하고 제목 및 소제목을 사용하여 쉽게 탐색 할 수 있습니다. 목차와 더 긴 문서에 대한 색인을 포함하십시오. 복잡한 개념을 설명하기 위해 다이어그램, 스크린 샷 및 비디오와 같은 비주얼을 사용하십시오.

다양한 유형의 소프트웨어 문서는 무엇입니까?

시스템 문서, 사용자 문서, 사용자 문서, 사용자 문서, 사용자 문서, 사용자 문서를 포함한 여러 유형의 소프트웨어 문서가 있습니다. 기술 문서. 시스템 문서는 아키텍처 및 데이터 흐름을 포함한 소프트웨어 시스템의 개요를 제공합니다. 사용자 문서는 소프트웨어 사용 방법에 대한 지침을 제공하고 사용자 설명서 및 도움말 안내서를 포함합니다. 기술 문서는 개발자를위한 것이며 코드 댓글, API 문서 및 개발 안내서가 포함되어 있습니다.

소프트웨어 문서를 얼마나 자주 업데이트해야합니까?

소프트웨어 문서는 소프트웨어. 새로운 기능이 추가되거나 기존 기능이 수정되거나 버그가 수정 되었기 때문일 수 있습니다. 또한 문서를 정기적으로 검토하여 여전히 정확하고 관련성이 있는지 확인하는 것이 좋습니다. 소프트웨어 문서를 작성하는 데 사용할 수있는 도구는 무엇입니까?

워드 프로세서, 문서 생성기 및 전문 문서 도구를 포함하여 소프트웨어 문서를 작성하는 데 사용할 수있는 많은 도구가 있습니다. 인기있는 옵션에는 Microsoft Word, Google Docs, Doxygen 및 Sphinx가 있습니다. 도구의 선택은 특정 요구 사항과 소프트웨어의 복잡성에 따라 다릅니다.

소프트웨어 문서의 품질을 어떻게 보장 할 수 있습니까?

소프트웨어 문서의 품질을 보장하려면 항상 검토하십시오. 작업을 철저히 편집하십시오. 동료 나 전문 편집자가 귀하의 문서를 검토하도록하는 것을 고려하십시오. 문서 전체에서 일관된 스타일과 형식을 사용하십시오. 정보가 정확하고 최신이며 관련이 있는지 확인하십시오. 마지막으로, 개선을위한 영역을 식별하기 위해 사용자로부터 피드백을 얻는 것을 고려하십시오.

소프트웨어 문서에서 영상의 역할은 무엇입니까?

영상은 소프트웨어 문서에서 중요한 역할을합니다. 그들은 복잡한 개념을 설명하여 이해하기 쉽도록 도울 수 있습니다. 또한 큰 텍스트 블록을 분해하여 문서를 더 읽기 쉽게 만들 수 있습니다. 비주얼의 예로는 다이어그램, 스크린 샷, 흐름도 및 비디오가 포함됩니다.

소프트웨어 문서를보다 매력적으로 만드는 방법은 무엇입니까?

소프트웨어 문서를보다 매력적으로 만들려면 대화 톤과 활성 음성을 사용하십시오. . 비주얼과 총알 포인트로 큰 텍스트 블록을 분해하십시오. 개념을 설명하기 위해 예와 사례 연구를 사용하십시오. 적절한 경우 퀴즈 나 연습과 같은 대화식 요소를 포함시킵니다.

소프트웨어 문서에서 일관성의 중요성은 무엇입니까?

문서를 쉽게 읽고 이해할 수 있도록 소프트웨어 문서에서 일관성이 중요합니다. 또한 문서에 전문적인 모양과 느낌을줍니다. 일관성은 언어, 스타일, 형식 및 비주얼에 적용됩니다.

소프트웨어 문서 작성에서 기술을 향상시키는 방법

소프트웨어 문서 작성 기술을 향상시키고 정기적으로 쓰기 연습을하십시오. 다른 소프트웨어 문서를 읽고 배우십시오. 기술 작문에 관한 과정이나 워크샵을 수강하십시오. 당신의 일에 대한 피드백을 찾고 비판에 개방적입니다. 소프트웨어 문서의 최신 트렌드 및 모범 사례로 업데이트하십시오.

위 내용은 첫 번째 소프트웨어 문서 작성 가이드의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!