이 페이지에는 Google Season of Docs에서 승인된 테크니컬 라이팅 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- 줄리아 언어
- 테크니컬 라이터:
- mkg33
- 프로젝트 이름:
- 과학적 머신러닝의 통합 문서
- 프로젝트 기간:
- 장기 실행 (5개월)
Project description
이 영역은 개선의 여지가 많기 때문에 SciML 조직 통합 작업을 하고 싶은데 이 프로젝트를 완료하면 줄리아 프로그래머와 SciML의 적극적인 기여자/유지관리 담당자 모두에게 즉각적인 이점이 있을 것입니다. SciML 전반에 흩어져 있는 패키지는 몇 가지 유용한 도구를 제공하지만, 특히 신규 사용자의 경우 사용자가 패키지를 찾아 당면 문제에 적용할 수 없다는 이유로 항상 알아채지 못할 위험이 있습니다.
이 패키지의 주된 목적이 프로그래머의 광범위한 잠재고객 (초보 및 전문가 등)에게 도달하는 것이라는 점을 고려할 때 다소 실망스러울 수 있습니다. 위에 설명된 상황을 피하기 위해 SciML 문서의 '첫 페이지'를 철저히 수정하고 사용자가 관련 패키지를 탐색하고 성장하는 생태계를 탐색하는 데 사용할 수 있는 일종의 허브를 만들 것을 제안합니다. 또한 경험이 풍부한 사용자에게 가치 있는 참고 자료가 되고 업무를 보다 효율적으로 하는 데 도움이 될 수 있습니다.
먼저 모든 개별 패키지의 기존 문서에서 가장 기본적인 스타일 문제 (예: 맞춤법, 구두점, 문법 등)를 수정해야 합니다. 스타일 일관성을 보장하려면 SciML에 구체적인 스타일 가이드가 있어야 합니다 (소급 변경 및 향후 참조에 필수적임). 처음부터 다시 시작하는 것은 시간 낭비일 것입니다. 대신 기존 Julia 규칙을 기반으로 하고 SciML 관련 문제에 대한 새로운 전체를 포함해야 합니다.
스타일 가이드가 완성되면 프로젝트의 두 번째 단계에서 현재 문서를 수정하려고 합니다. 이렇게 하면 문서가 더 전문적이고 안정적으로 보입니다. 이 작업에 대한 저의 접근 방식을 보여주는 여러 개의 pull 요청을 이미 만들었습니다. 이 단계에서는 효율적인 인용 시스템을 고안하고 구현하려고 합니다. 가장 먼저 할 일은 오래된 인용 페이지를 업데이트하는 것입니다.
가장 중요한 세 번째 단계는 분산된 패키지 간의 상호작용을 강조하는 SciML 로드맵 설계입니다. 두 패키지 간의 응집력이 강할수록 (문제 또는 코드 자체와 관련됨) '참조' 목록에 더 가깝게 표시되어야 합니다. 두 개의 추천 키, 즉 코드 유사성과 문제 유사성을 위한 키를 만드는 것이 좋습니다. 이렇게 하면 사용자는 각 저장소와 문서를 힘들게 탐색하는 것보다 훨씬 더 유용할 수 있는 다른 패키지를 식별할 수 있습니다. 패키지 간에 가능한 모든 연결을 나열하기보다는 큰 연결에 집중하고 작은 패키지로 링크를 표시하려고 합니다 (이 방법은 다른 패키지와의 연결을 강조해야 하는 업데이트 튜토리얼로도 확장될 것입니다). 이 접근 방식을 사용하면 패키지 조합을 모두 열거하지 않고도 '참조' 목록에 정보를 제공할 수 있습니다.