이 페이지에는 Google Season of Docs에서 승인된 테크니컬 라이팅 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- ScummVM
- 테크니컬 라이터:
- b-gent
- 프로젝트 이름:
- Doxygen을 통한 소스 코드 문서 개선
- 프로젝트 기간:
- 표준 기간 (3개월)
Project description
최신 ScummVM API (소스 코드) 문서는 다음 위치에 게시되어 있습니다. https://doxygen.scummvm.org/modules.html
안타깝게도 다음과 같은 여러 영역에서 이러한 니즈가 부족합니다.
1) 사실상 구조가 없으며 모든 정보가 같은 레벨에 떠 있습니다.
2) C++ 요소가 문서화되어 있지 않으며 일부 요소가 전혀 문서화되지 않았습니다. 조직에서 이를 주요 문제 중 하나로 언급합니다.
3) 오래되었거나 지원 중단된 콘텐츠가 출력에 계속 표시됩니다.
4) Doxygen 태그의 언어와 사용이 더욱 일관적으로 이루어져야 합니다. 이를 위한 일련의 규칙이 필요하며, 이 규칙이 이 프로젝트의 향후 문서 스타일 가이드의 기반이 될 수 있습니다.
5) 이 페이지에서 사용하는 doxygen CSS를 ScummVM 웹사이트(https://www.scummvm.org)와 더 유사하게 만들 수 있습니다.
이러한 모든 문제는 Docs 시즌 프로젝트에서 해결할 수 있습니다.
이번 Docs 시즌 애플리케이션에는 몇 가지 잠재적인 개선사항을 설명하기 위해 프로젝트에서 연 초안 PR이 함께 제공됩니다. https://github.com/scummvm/scummvm/pull/2361 여기에 포함된 내용과 차이점을 보려면 설명을 참조하세요.
PR에 포함되는 사항은 다음과 같습니다.
1) 잠재적인 신규 참여자, 그리고 일반적으로 현재의 API 문서를 보는 모든 사람에게 가장 혼란스러운 부분은 구조가 부족한 것이라고 생각합니다. 구조화된 API 문서를 도입하면 가독성, 검색 가능성, 결과적으로 문서 세트 사용성이 향상됩니다. 그래서 PR에서 'common' 폴더의 모든 헤더 파일에 doxygen 그룹을 도입합니다. 이 새로운 구조에서는 누군가가 OS 관련 API 문서를 찾고자 하는 경우 탐색에서 쉽게 찾을 수 있습니다.
2) 이 문서를 작성할 수 있도록 새로운 Doxygen 구성 파일이 설정되었습니다.
3) 문서 세트 전체에서 사용되는 모든 링크를 단일 소스로 사용할 수 있는 'links.doxyfile' 파일 독소원소를 사용할 때 유용한 메커니즘입니다.
4) 수정된 doxygen CSS. 이는 현재 다른 오픈소스 프로젝트에서 가져온 것으로, 시작에 불과합니다. Doxygen 페이지의 디자인과 분위기가 ScummVM 웹페이지와 거의 일치하는 것이 이상적입니다.
PR에서 다루지 않지만 확실히 작업해야 하는 것은 콘텐츠 자체입니다. 여기서 문서화되지 않은 코드의 필수 부분, 충분히 문서화되지 않은 부분 또는 문서에서 제거해야 하는 오래된 코드 부분을 식별하는 것을 의미합니다. 이전에 이 프로젝트에 참여한 적이 없기 때문에 이를 위해서는 멘토의 안내가 필요합니다.
물론, PR에서 무엇을 구현할지 여부는 조직과 논의해야 합니다. 제 생각에는 행동이 말보다 더 크게 말해야 한다는 생각이었기 때문에 애플리케이션에서 단순히 설명하는 것이 아니라 무엇을 할 수 있는지 보여드리기로 했습니다.
조직에서 다음과 같이 이 프로젝트에 대한 대략적인 타임라인을 제공했습니다. 1주차/1주/백엔드 작업(1주차/1주차/백엔드 작업) 1주차/1주차/백엔드 작업 2주/14주 이전) 1주/14주차 제안 토론 및 검토 1주차(9/14) Doxygen 빌드 설정 2주차(9/21) Doxygen 스킨 새로고침(우선순위 낮음) 3주차(9/28) 일반 코드 - OSystem, FS, 데이터 0주
제안할 유일한 변경 사항은 앞서 말씀드린 것처럼 구조 작업을 시작하는 것입니다. 1주 차 및 2주 차에 doxygen 빌드 설정 (대부분 이미 완료됨)과 Doxygen 스킨 리프레시와 함께 할 수 있습니다. 그런 다음 멘토와 함께 여러 영역을 하나씩 살펴보면서 문제를 파악하고 약물 문서를 개선하는 것이 가장 합리적이라는 데 동의합니다.
이 프로젝트는 표준 길이 프로젝트이지만 GSoD 프로젝트가 완료된 후 수행 할 수있는 다른 개선 사항이 API 문서와 관련하여 있다고 확신합니다. 예를 들어, 문서 스타일 가이드를 마련하여 위키에 추가하면 기여자가 추가하려는 코드를 어떻게 문서화해야 하는지 알 수 있습니다.
GSoD가 종료된 후 이와 같은 작업을 기꺼이 도와드리겠습니다. ScummVM에서 API 문서의 품질과 사용성을 확인하는 테크니컬 라이터를 고용할 수 있을 것이라고 확신합니다. 또한 향후에 플러그인 사용 방법에 관한 가이드를 만드는 등 도움을 드릴 수 있는 다른 문서 프로젝트도 있습니다.