이미 개발 한 프로젝트를 문서화하는 데 어떤 옵션을 사용할 수 있는지 알고 싶습니다. 작업 한 개발자는 단일 페이지의 문서조차 작성하지 않았기 때문입니다.
이 프로젝트에는 지난 2 년 동안이 프로젝트에서 일한 개발자가 작성하고 수정 한 기능을 가진 많은 스크립트 페이지 외에 다른 세부 정보가 없습니다. 내가 가진 것은 데이터베이스 스키마와 프로젝트 파일뿐입니다. 이 프로젝트를 구성하고 문서화하여 향후이 프로젝트를 수행 할 개발자에게 도움이되도록 문서화 할 수있는 방법이 있는지 알고 싶습니다.
이 프로젝트는 PHP와 MySQL로 개발되었습니다. 함수의 주석이 잘못되어 doxygen으로 실행할 때 좋은 결과를 얻을 수 없습니다.
답변
누가 문서를 읽을 것인가? 설명서는 무엇을 위해 사용됩니까? 이것들은 대답해야 할 가장 중요한 질문입니다. 예를 들어, 유지 보수 개발자를위한 문서는 구조에 중점을 두는 반면, 제품과 통합 된 개발자를위한 문서는 웹 서비스 및 데이터베이스 구조에 중점을 둡니다.
일반적으로 필요한만큼 많은 문서를 작성하십시오. 많은 조직에서는 누군가가 모범 사례를 주장하기 때문에 문서를 요구하지만 문서는 먼지를 모으게됩니다.
사람들이 실제로 문서를 사용한다고 가정 할 때 코드와 데이터베이스를 가장 작은 수준으로 캡처하지 마십시오. 개발자는 축소 코드를 살펴 봅니다. 대신 코드에서 명확하지 않은 세부 사항에 초점을 맞추십시오 ( 예 :
- 제품 이 사용 하는 사용 사례 . 제품의 수명을 고려하면 어려울 수 있지만 제품의 용도를 파악하는 것은 비 기술적 인 독자와 테스터에게 중요한 맥락을 제공합니다. 시장의 경쟁자는 누구입니까 (있는 경우)? 제품 범위에서 제외 된 것이 있습니까?
- 명확한 비 기능적 요구 사항 . 예를 들어, 제품이 특정 볼륨을 처리하도록 작성 되었습니까? 데이터는 몇 살입니까? 캐싱은 어디에 사용됩니까? 사용자는 어떻게 인증됩니까? 액세스 제어는 어떻게 작동합니까?
- 컨텍스트도 모니터링 등, 다른 데이터베이스와 같은 시스템, 인증 소스, 백업과의 상호 작용을 도시.
- (알려진 경우) 위험 및 의사 결정 기록부 와 함께 위험 이 완화 된 방법 . 이것은 회상하기가 어려울 수 있지만 디자인에 영향을 미치는 중요한 결정이 종종 있습니다. 당신이 알고있는 것을 포착하십시오.
- 일반적인 디자인 패턴 또는 디자인 지침 . 예를 들어, 데이터베이스에 액세스하는 표준 방법이 있습니까? 코딩 또는 명명 표준이 있습니까?
- 일반적으로 플로우 차트 또는 UML 활동 또는 시퀀스 다이어그램을 사용하는 중요 코드 경로 프로젝트에는 아무 것도 없을 수 있지만 이들은 일반적으로 비즈니스 사용자가 표현한 것입니다.
이 정보를 모두 사용할 수없는 경우에도 지금 시작하십시오 . 당신을 따르는 개발자들은 당신에게 감사 할 것입니다.
기술 수준이 낮은 사람은 액세스하기 어렵지만 우수한 자동화 단위 테스트 또는 테스트 사례 도 유용한 문서가 될 수 있습니다.
또한 문서를 포함 하기 위해 문화를 바꿔야 할 것 같습니다 . 소규모로 시작하는 것이 가장 이상적이지만 최소한의 문서 수준이 될 때까지 프로젝트를 “완료”해서는 안됩니다. 위의 내용을 제어 할 수 있으므로 가장 어려운 단계 일 것입니다. 이것은 다른 사람들이 사야 할 것입니다. 그러나 특히 다음 프로젝트에 좋은 문서가 제공되는 경우 가장 보람이있을 수 있습니다.
답변
과거에는 다양한 제품 소유자 또는 고급 사용자와 함께 일차 사용 사례를 살펴보고 일련의 테스트로 문서화하여 이와 같은 상황을 관리했습니다. 나중에 변경을 시작할 때이를 시스템의 기준으로 사용할 수 있습니다. 또한 소유자 나 유스 케이스가없고 잠재적으로 삭제 될 수있는 시스템 영역을 식별하는 데 도움이 될 수 있습니다.
그것은 모두 실제로 시스템의 크기에 달려 있습니다. 이해 관계자가 많은 복잡한 시스템 인 경우 어떤 기능이 존재하고 어느 부분이 만족되는지를 상세히 설명하는 고급 구성 요소 다이어그램을 작성할 수 있습니다. 이는 시스템 설계에서 아키텍처 문제를 식별하는 데 매우 유용 할 수 있습니다.
일반적으로 구식 문서는 오래되어 개발자가 그리워하지 않기 때문에 구식 문서를 사용하지 않는 것이 좋습니다. 저는 항상 시스템이 발전함에 따라 유지 될 테스트 형태로 실제 문서를 작성하려고합니다.
답변
가장 먼저, 대상 고객은 누구입니까? 미래의 개발자 또는 다른 사업가? 그 질문에 대한 답을 명심하십시오.
다른 사람들이 말했듯이, 높은 수준의 설명이 가장 먼저 필요합니다. 시스템이 더 넓은 일에서 무엇을하려고하는지 설명하십시오. 그것이 무엇을 실행하는지, 그것이 어떻게 네트워크에 적합하고 다른 시스템과 대화하는지 설명하십시오. 그런 다음 각 화면을 살펴보고 스크린 샷을 찍고 화면의 기능과 시스템의 다른 부분과 상호 작용하는 방법에 대해 간단히 설명합니다. 개발자를 위해 앱을 처음 설명하는 것처럼 대화를 유지하십시오. 결국, 그것은 의사의 요점입니다 (나는 가정합니다).
복잡한 처리 또는 논리 상태 다이어그램, 데이터 흐름 다이어그램 또는 시퀀스 다이어그램을 사용합니다. 엔터티 다이어그램을 선택한 다음 DB 스키마 디자인을 수행하십시오 (두 가지 다른 것!). 아마도 기본 클래스 다이어그램이지만 간단하게 유지하면 관심있는 주요 내용 만 주목하면 개발자는 코드를 보면서 해당 내용을 파악할 수 있습니다.
시작하는 데 문제가있는 경우 방 바로 옆에 다른 개발자가 있다고 가정 해보십시오. 시스템에 대한 첫 번째 사실을 모르는 사람은 비교적 참을성이 없어서 그 요점을 알아야합니다. 그런 다음 설명을 시작하고 말한 내용을 적어 두십시오.
답변
이전 제안은 모두 좋은 제안이지만 사용자 커뮤니티에서 임시 문서를 직접 만든 경우 조사하는 것도 고려할 것입니다. 귀하의 질문에 귀하의 ‘제품'(2 년간 존재) 버전이 사용자에게 공개되었는지 여부는 명시되지 않았습니다. 사용 중이고 공식 문서가없는 경우 문서가 필요하지 않거나 기초가 될 수 있지만 사용자가 필수적으로 인식 할 수있는 ‘비공식’문서가있을 수 있습니다. 중요한 API, 검색 포럼, 고급 사용자 요청, 질문 및 답변 사이트 검색을 나타낼 수있는 인공물을 웹에서 검색해보십시오. 가능하면 기술 또는 비즈니스 요구를 충족시키는 문서를 작성하십시오.
답변
문제는 지금 또는 현재 상태로 문서화 하시겠습니까?
내가 당신의 질문에서 읽은 것은 당신이 API 문서에 대해 생각하고 있으며 많은 사용자 문서가 아니며 코드가 그렇게 잘 유지되고 암호가 아닐 수 있습니다.
지금 문서를 작성하면 코드를 리팩터링하면 대부분의 작업을 버릴 수 있습니다.
나는 다음과 같은 접근법을 취할 것입니다 :
- 일반적인 모범 사례를 준수하여 가능한 한 문서를 불필요하게 만듭니다. 직관적으로 이해할 수있는 좋은 클래스 이름, 메소드 이름, 변수 이름을 선택하십시오.
- 거대한 몬스터 클래스 및 / 또는 기능을 이해하기
- PHPdoc 주석 사용-도구를 사용하여 API 문서 작성
- 테스트 작성 : 테스트는 코드의 기능을 이해하거나 정의하는 데 도움이됩니다.
이제, 당신은 여전히 문서화되지 않은 것들을 가지고 있습니다 : 이것은 일반적인 개념, 아키텍처 등일 수 있습니다.이를 위해, 저는 실제로 문서를 작성할 것입니다 – 그러나 실제로 유용하고 유용한 것만 쓰십시오.