소프트웨어 매뉴얼

Software documentation

소프트웨어 매뉴얼은 컴퓨터 소프트웨어에 부속되어 있거나 소스 코드에 포함되어 있는 문서 또는 그림입니다.이 문서에서는 소프트웨어의 동작 방법 또는 사용 방법에 대해 설명하고 있으며, 역할별로 의미가 다를 수 있습니다.

문서화는 소프트웨어 엔지니어링의 중요한 부분입니다.문서의 종류는 다음과 같습니다.

  • 요건 – 시스템의 속성, 기능, 특성 또는 품질을 식별하는 문장.이것은 향후 또는 향후의 실시를 위한 기초입니다.
  • 아키텍처/설계– 소프트웨어 개요소프트웨어 컴포넌트 설계에 사용되는 환경 및 구성 원칙과의 관계를 포함합니다.
  • 기술 – 코드, 알고리즘, 인터페이스 및 API 문서.
  • 최종 사용자 – 최종 사용자, 시스템 관리자 및 지원 직원을 위한 매뉴얼.
  • 마케팅 – 제품 마케팅 방법 및 시장 수요 분석

요건 문서

요건 문서란 특정 소프트웨어가 수행하는 작업 또는 수행해야 할 작업에 대한 설명입니다.소프트웨어의 기능이나 동작의 의도를 전달하기 위해 개발 전반에 걸쳐 사용됩니다.또, 소프트웨어의 동작에 관한 합의 또는 합의의 기초로서도 사용됩니다.요건은 최종 사용자, 고객, 프로젝트 매니저, 세일즈, 마케팅, 소프트웨어 아키텍트, 사용성 엔지니어, 인터랙션 디자이너, 개발자, 테스터 등 소프트웨어 제작에 관여하는 모든 사람이 작성 및 소비합니다.

요구사항은 다양한 스타일, 표기법 및 격식을 갖추고 있습니다.요구사항은 목표와 같은 것(예: 분산 작업 환경), 설계에 가까운 것(예: 구성 파일을 마우스 오른쪽 버튼으로 클릭하고 '빌드' 기능을 선택하면 빌드를 시작할 수 있음), 그리고 그 사이의 모든 것이 될 수 있습니다.그것들은 자연어로 된 문장, 그려진 그림, 상세한 수학 공식, 그리고 그것들의 조합으로 지정될 수 있다.

요구사항 문서의 다양성과 복잡성으로 인해 입증된 과제가 됩니다.요건은 암묵적이고 파악하기 어려울 수 있습니다.어느 정도의 문서가 필요한지, 어떤 종류의 문서가 필요한지, 아키텍처와 설계 문서에 어느 정도 남겨질 수 있는지 정확히 알 수 없고, 문서를 읽고 사용하는 사람의 다양성을 고려할 때 요건을 어떻게 문서화해야 하는지 알 수 없습니다.따라서 요건 문서는 불완전하거나 존재하지 않는 경우가 많습니다.적절한 요건의 문서화가 없으면 소프트웨어 변경이 어려워지기 때문에 오류가 발생하기 쉬워지고(소프트웨어 품질이 저하됨), 시간이 많이 소요됩니다(비용이 많이 듭니다.

요건 문서의 필요성은 일반적으로 제품의 복잡성, 제품의 영향 및 소프트웨어의 기대 수명과 관련되어 있습니다.소프트웨어가 매우 복잡하거나 많은 사람에 의해 개발된 경우(예를 들어 휴대폰 소프트웨어) 요건은 달성해야 할 사항을 더 잘 전달하는 데 도움이 될 수 있습니다.소프트웨어가 안전에 중요하며 인간의 삶에 부정적인 영향을 미칠 수 있는 경우(예: 원자력 시스템, 의료 장비, 기계 장비) 보다 공식적인 요건 문서가 필요한 경우가 많다.소프트웨어의 수명이 1~2개월밖에 되지 않을 것으로 예상되는 경우(예를 들어 특정 캠페인용으로 개발된 매우 작은 휴대 전화 애플리케이션 등) 요건 문서는 거의 필요하지 않을 수 있습니다.소프트웨어가 나중에 구축되는 첫 번째 릴리스인 경우 요건 매뉴얼은 소프트웨어 변경을 관리하고 소프트웨어 변경 시 소프트웨어에서 파손된 것이 없음을 확인할 때 매우 유용합니다.

일반적으로 요구사항은 요구사항 문서에 명시되어 있습니다(예: 워드프로세서 애플리케이션 및 스프레드시트 애플리케이션 사용).요건 문서(및 일반적으로 소프트웨어 문서)의 복잡성과 변화하는 특성을 관리하기 위해 데이터베이스 중심 시스템과 특수 목적의 요건 관리 도구가 권장됩니다.

아키텍처 설계 문서

아키텍처 문서(소프트웨어 아키텍처 설명이라고도 함)는 특별한 유형의 설계 문서입니다.어떤 면에서 아키텍처 문서는 코드의 세 번째 파생 문서입니다(설계 문서는 두 번째 파생 문서, 코드 문서는 첫 번째 파생 문서).아키텍처 문서에는 코드 자체에 고유한 내용이 거의 없습니다.이 문서에서는 특정 루틴을 프로그래밍하는 방법이나 특정 루틴이 존재하는 이유를 설명하지 않고, 대신 그러한 루틴의 존재에 동기를 부여하는 일반적인 요건을 제시합니다.좋은 아키텍처 문서는 세부 사항은 부족하지만 설명은 두껍다.저수준 설계에 대한 접근방식을 제안할 수 있지만 실제 탐사 무역 연구는 다른 문서에 맡긴다.

또 다른 유형의 설계 문서는 비교 문서 또는 업계 연구입니다.이것은 종종 백서의 형태를 취합니다.시스템의 한 가지 특정 측면에 초점을 맞추고 대체 접근법을 제안합니다.사용자 인터페이스, 코드, 설계 또는 아키텍처 수준일 수 있습니다.상황의 개요를 설명하고, 하나 이상의 대안을 설명하며, 각각의 장단점을 열거합니다.좋은 무역 연구 문서는 연구에 치중하고, (독자를 현혹하기 위해 둔한 전문 용어에 크게 의존하지 않고) 아이디어를 명확하게 표현하며, 가장 중요한 것은 공정하다.최선의 솔루션 제공 비용을 정직하고 명확하게 설명해야 합니다.무역 연구의 목적은 특정 관점을 추진하는 것이 아니라 최선의 해결책을 고안하는 것입니다.결론을 제시하지 않거나 어떤 대안도 변경을 보장하기에 기준선보다 충분히 낫지 않다고 결론짓는 것은 전적으로 허용된다.마케팅 기법이 아니라 과학적 노력으로 접근해야 한다.

엔터프라이즈 소프트웨어 개발에서 설계 문서의 매우 중요한 부분은 데이터베이스 설계 문서(DD)입니다.여기에는 개념, 논리 및 물리적 설계 요소가 포함되어 있습니다.DDD에는 데이터베이스와 상호작용하는 사용자에게 필요한 공식 정보가 포함되어 있습니다.준비의 목적은 장면 내의 모든 플레이어가 사용할 공통 소스를 만드는 것입니다.잠재적인 사용자는 다음과 같습니다.

릴레이셔널 데이터베이스 시스템에 대해 설명할 때 이 문서에는 다음 부분이 포함되어야 합니다.

  • 엔티티 - 다음 정보와 명확한 정의를 포함하는 관계 스키마(확장 여부)
    • 엔티티 세트와 그 속성
    • 관계와 그 속성
    • 각 엔티티 세트의 후보 키
    • 속성 및 태플 기반 제약 조건
  • 다음 정보를 포함한 관계형 스키마:
    • 테이블, 속성 및 속성
    • 표시
    • 프라이머리 키, 외부 키,
    • 참조 제약의 카디널리티
    • 참조 제약의 캐스케이드 정책
    • 프라이머리 키

장면에서 모든 배우가 사용할 모든 정보를 포함하는 것이 매우 중요합니다.데이터베이스에서도 변경 사항이 발생하므로 문서를 업데이트하는 것도 매우 중요합니다.

테크니컬 문서

주요 기사:테크니컬 문서

소스 코드와 관련된 코드 문서(README 파일 및 API 문서 포함)는 완전해야 하지만 시간이 너무 많이 걸리거나 유지보수가 어려울 정도로 상세하지는 않습니다.API 라이터에 의해 문서화되어 있는 소프트웨어 애플리케이션 또는 소프트웨어 제품 특유의 사용법과 개요에 관한 각종 매뉴얼 가이드가 일반적으로 있습니다.이 매뉴얼은 개발자, 테스터 및 최종 사용자가 사용할 수 있습니다.오늘날 전력, 에너지, 운송, 네트워크, 항공우주, 안전, 보안, 산업 자동화 및 기타 다양한 분야에서 많은 하이엔드 애플리케이션이 사용되고 있습니다.아키텍처 변경에 따라 정보의 기본 수준과 고급 수준이 일정 기간 변경될 수 있기 때문에 이러한 조직에서는 기술 문서가 중요해지고 있습니다.

코드 문서는 종종 참조 가이드 스타일로 구성되어 프로그래머가 임의의 함수 또는 클래스를 빠르게 검색할 수 있습니다.

소스 코드에 내장된 기술 문서

대부분의 경우 Doxygen, NDoc, Visual Expert, Javadoc, JSDoc, EiffelStudio, Sandcastle, ROBODoc, POD, TwinText, Universal Report 등의 도구를 사용하여 코드 문서를 자동 생성할 수 있습니다.즉, 소스코드 형식이나 참조용 매뉴얼에서 주석과 계약을 추출할 수 있습니다.

문서를 자동 생성한다는 아이디어는 프로그래머에게 다양한 이유로 매력적입니다.예를 들어 소스 코드 자체에서 추출되므로(예를 들어 코멘트를 통해), 프로그래머는 코드를 참조하면서 작성할 수 있으며, 문서화를 위해 소스 코드를 작성하는 데 사용한 것과 동일한 도구를 사용할 수 있습니다.따라서 문서를 보다 쉽게 최신 상태로 유지할 수 있습니다.

물론, 단점은 프로그래머만이 이러한 종류의 문서를 편집할 수 있다는 것입니다.또한 이러한 문서를 갱신하는 것은 프로그래머에게 달려 있습니다(예를 들어 cron 작업을 실행하여 문서를 야간에 갱신하는 것입니다.어떤 사람들은 이것을 사기라기보다는 프로로 특징지을 것이다.

리터럴 프로그래밍

존경받는 컴퓨터 과학자인 Donald Knuth는 문서화가 매우 어려운 과정일 수 있다고 지적하고 소스코드와 동시에 작성되고 자동수단으로 추출되는 리터럴한 프로그래밍을 지지해 왔습니다.프로그래밍 언어인 Haskell과 CoffeeScript는 단순한 형식의 리터리트 프로그래밍을 기본적으로 지원하지만 이 지원은 널리 사용되지 않습니다.

설명형 프로그래밍

설명형 프로그래밍은 실제 프로그래밍 상황에서 리터레이트 프로그래밍을 실제로 적용한 결과입니다.설명적 패러다임에서는 소스 코드와 문서를 별도로 저장할 것을 제안합니다.

대부분의 경우 소프트웨어 개발자는 소스 파일 자체의 일부가 아닌 정보를 생성하고 액세스할 수 있어야 합니다.이러한 주석은 일반적으로 코드 워크 및 포팅과 같은 여러 소프트웨어 개발 활동의 일부이며, 여기서 제3자 소스 코드는 기능적인 방법으로 분석됩니다.따라서 주석은 정식 문서 시스템이 진행을 방해하는 소프트웨어 개발 단계에서 개발자에게 도움이 될 수 있습니다.

사용자 매뉴얼

코드 문서와 달리 사용자 문서는 단순히 프로그램이 어떻게 사용되는지 설명합니다.

소프트웨어 라이브러리의 경우 코드 문서와 사용자 문서가 효과적으로 동등하고 결합할 가치가 있는 경우가 있지만, 일반적인 애플리케이션에서는 그렇지 않은 경우가 많습니다.

통상, 유저 메뉴얼에서는, 프로그램의 각 기능에 대해 설명하고, 유저가 이러한 기능을 실현하는데 도움이 됩니다.사용자 문서를 혼동하지 말고 최신 상태로 유지하는 것이 매우 중요합니다.사용자 문서는 특별한 방식으로 구성할 필요가 없지만, 완전한 색인을 가지는 것이 매우 중요합니다.일관성과 단순성도 매우 중요합니다.유저 메뉴얼은, 소프트웨어의 기능을 지정하는 계약을 구성하는 것으로 간주됩니다.API 라이터는 사용되는 소프트웨어 아키텍처와 프로그래밍 기술을 잘 알고 있기 때문에 우수한 사용자 문서를 작성하는 데 매우 능숙합니다.테크니컬 라이팅도 참조해 주세요.

유저 메뉴얼은, 다양한 온라인 형식과 [1]인쇄 형식으로 제작할 수 있습니다.다만, 유저 메뉴얼을 정리하는 방법에는 크게 3가지가 있습니다.

  1. 튜토리얼:튜토리얼 어프로치는 신규 사용자에게 가장 유용한 것으로 간주되며,[2] 이 어프로치에서는 특정 작업을 수행하는 각 단계를 안내합니다.
  2. 주제:챕터 또는 섹션이 하나의 특정 관심 영역에 집중되는 주제 접근법은 중간 사용자에게 더 일반적으로 사용됩니다.일부 저자는 사용자의 요구를 촉진하기 위해 지식 기반 기사를 통해 자신의 아이디어를 전달하는 것을 선호합니다.이 접근방식은 보통 정보기술과 [3]같은 역동적인 산업에 의해 실천되고 있습니다.
  3. 목록 또는 참조:구성 원칙의 마지막 유형은 명령 또는 작업이 단순히 알파벳 또는 논리적으로 나열되며, 종종 상호 참조 색인을 통해 분류됩니다.이 후자의 접근법은 자신이 찾고 있는 정보의 종류를 정확하게 알고 있는 고급 사용자에게 더욱 유용합니다.

소프트웨어 매뉴얼에 관한 사용자들의 일반적인 불만은 이들 3가지 접근법 중1개만 나머지 2개의 접근법 제외에 가깝다는 것입니다.일반적으로 PC용 소프트웨어 매뉴얼은 명령 또는 메뉴 항목에 대한 참조 정보만 제공하는 온라인 도움말에 한정됩니다.신규 사용자를 지도하거나 보다 경험이 많은 사용자가 프로그램을 최대한 활용할 수 있도록 돕는 일은 소프트웨어 개발자에 의해 종종 상당한 지원을 받는 개인 출판사에 맡겨집니다.

사용자 설명서 작성

다른 형식의 기술 문서와 마찬가지로 양호한 사용자 문서도 체계적인 개발 프로세스에서 이점을 얻을 수 있습니다.사용자 설명서의 경우 업계에서 일반적으로 발생하는 프로세스는 다음 [4]5단계로 구성됩니다.

  1. 프로세스의 기본 연구 [5]단계인 사용자 분석.
  2. 계획 또는 실제 문서 [6]단계
  3. 초안 검토는 이전 [7]단계에서 작성된 초안에 대한 피드백을 구하는 자체 설명 단계입니다.
  4. 사용성 테스트: 문서의 사용성을 [8]경험적으로 테스트합니다.
  5. 3단계와 4단계에서 수집된 정보를 최종 초안 작성에 사용하는 마지막 단계인 편집.

문서화와 신속한 개발 논란

"개발자들 사이에서 문서화에 대한 저항은 잘 알려져 있으며 [9]강조할 필요가 없습니다."이 상황은 특히 신속한 변화를 위한 소프트웨어 개발에서 많이 발생합니다.이러한 방법론은 가치를 직접 가져오지 않는 불필요한 액티비티를 회피하려고 하기 때문입니다.특히 Agile Manifesto는 "포괄적인 문서보다 소프트웨어를 사용하는 것"을 중시하며, 이는 "우리는 모든 시간을 코딩에 소비하고 싶다"는 비아냥거림으로 해석될 수 있습니다.실제 프로그래머는 [10]문서를 작성하지 않습니다.

그러나 소프트웨어 엔지니어링 전문가를 대상으로 한 설문조사에 따르면 신속한 변화를 위한 개발에는 문서화가 결코 필요하지 않은 것으로 나타났습니다.그러나 개발에는 동기부여 문제가 있으며, 신속한 개발에 맞춘 문서화 방법(예: 평판 시스템 및 게임화)이 [11][12]필요할 수 있습니다.

마케팅 문서

많은 응용 프로그램에서는 일상적인 관찰자가 제품에 대해 더 많은 시간을 할애할 수 있도록 홍보 자료가 필요합니다.이 문서에는 다음 3가지 목적이 있습니다.

  1. 제품에 대한 잠재적 사용자를 자극하고 제품에 더 관여하려는 욕구를 심어줍니다.
  2. 제품이 정확히 어떤 역할을 하는지 알려주고, 고객이 받을 수 있는 기대치와 일치하도록 합니다.
  3. 다른 대안에 대한 본 제품의 위치를 설명합니다.

「 」를 참조해 주세요.

메모들

  1. ^ "RH Earle, MA Rosso, KE Alexander (2015) User preferences of software documentation genres. Proceedings of the 33rd Annual International Conference on the Design of Communication (ACM SIGDOC)".
  2. ^ Woelz, Carlos. "The KDE Documentation Primer". Retrieved 15 June 2009.
  3. ^ Microsoft. "Knowledge Base Articles for Driver Development". Retrieved 15 June 2009.
  4. ^ 토마스 T.바커, 소프트웨어 문서 작성, 서문, xxiv.제2판 테크니컬 커뮤니케이션의 Allyn & Bacon 시리즈의 일부.Upper Saddle River: Pearson Education,ISBN 0321103289 2013년 5월 13일 Wayback Machine에서 아카이브 완료
  5. ^ 바커, 118페이지
  6. ^ 바커, 173페이지
  7. ^ 바커, 217페이지
  8. ^ 바커, 240페이지
  9. ^ 허블렙, 제임스 D, 그리고 모이트라, 데펜드라.입력: IEEE 소프트웨어, vol. 18, No. 2, 페이지 16-20, 2001년 3월/4월
  10. ^ Rakitin, Steven, "Manifesto는 냉소를 이끌어낸다." IEEE Computer, vol. 34, no. 12, p.4,
  11. ^ 프라우즈, 크리스찬 R., 그리고 조야 두르딕."아키텍처 설계 및 문서화:신속한 개발로 낭비가 발생합니까?"in: ICSSP(International Conference on Software and System Process), IEEE, 2012.
  12. ^ 셀릭, 브랜"신속한 문서 작성자 있나요?"입력: IEEE 소프트웨어, vol. 26, no. 6, 페이지 11-12, 2009