이 페이지에는 Google Season of Docs에 선정된 기술 문서 작성 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- Linux Foundation
- 기술 문서 작성자:
- boron
- 프로젝트 이름:
- 문서 호스팅 및 생성 재작업, 시작하기 페이지 및 개발자 가이드 재구성
- 프로젝트 기간:
- 표준 기간 (3개월)
프로젝트 설명
개요 :
문서는 최종 사용자와 개발자가 제품 또는 서비스를 사용할 수 있도록 지원하기 위해 설계되었습니다. 좋은 문서는 사용자가 소프트웨어, 기능, 팁, 유용한 정보 사용 방법을 배우고 소프트웨어 사용 시 발생하는 일반적인 문제를 해결할 수 있는 방법을 제공하므로 매우 중요합니다. 또한 지원 비용을 절감하고 제품의 기업 및 오픈소스 정체성의 일부입니다. 좋은 문서는 제품과 개발팀의 건전성을 나타냅니다.
좋은 문서가 없으면 사용자는 위 작업을 효과적이고 효율적으로 수행하는 방법을 알 수 없습니다. 문서는 제품의 성공을 보장하는 데 중추적인 역할을 할 수 있습니다. 훌륭한 커뮤니케이션은 모든 비즈니스 또는 제품의 핵심이며, 훌륭한 문서는 이러한 커뮤니케이션을 모든 사용자가 성공을 위해 액세스할 수 있는 관리 가능한 프레임워크에 배치합니다.
모든 문서 사이트에는 좋은 빌드 및 호스팅 워크플로 파이프라인이 필요합니다. AGL과 같은 조직에서는 여러 버전과 많은 상세 문서가 있으므로 문서 파일 (마크다운)이 여러 저장소에 분산되어 유지관리 및 업데이트 작업이 매우 복잡하고 시간이 많이 걸립니다.
현재 상태 :
- AGL 문서 웹사이트는 다양한 저장소에서 가져온 마크다운 파일 모음을 기반으로 합니다.
- 문서 페이지는 현재 Cordova 프로젝트의 엔진을 사용하여 마크다운으로 개별 소스 내에서 호스팅됩니다.
- 이로 인해 문서 빌드 및 호스팅 프로세스를 위한 4개의 저장소 설정이 이루어집니다.
- Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : Jekyll 웹사이트 템플릿이 포함되어 있습니다.
- Docs-tools [https://github.com/automotive-grade-linux/docs-tools] : 마크다운 파일에서 기술 웹사이트를 자동으로 생성하는 도구가 포함되어 있습니다.
- Docs-sources [https://github.com/automotive-grade-linux/docs-sources] : 일반 문서, 가이드의 소스 (마크다운 [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs])입니다.
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : 문서 사이트 [https://gist.github.com/growupboron/docs.automotivelinux.org]에 배포된 GitHub 페이지 저장소입니다.
- docs-tools [https://github.com/automotive-grade-linux/docs-tools] 에서 사용할 수 있는 도구 (스크립트)는 docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]에 있는 fetched_files.yml에 따라 모든 마크다운 파일을 수집하고 템플릿화합니다.
- agl 문서 웹사이트 생성의 현재 워크플로 : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
- section_version.yml에는 모든 책 YAML 파일의 링크가 포함되어 있으며, 원격 저장소에서 docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]로 모든 책 YAML 파일을 가져옵니다. 책 YAML 파일에는 원격 저장소의 마크다운 파일에 대한 모든 URL이 포함되어 있습니다.
- 모든 마크다운 파일을 가져오면 도구가 docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] 에서 AGL 문서 웹사이트를 생성하는 프로세스를 진행하며, 이는 그에 따라 배포됩니다.
- 현재 파이프라인 유지관리 프로세스는 사용자 및 개발자, 특히 신규 기여자에게 친숙하지 않습니다. 이 워크플로 파이프라인 (빌드 및 호스팅)은 개발자가 문서 생성 및 배포 워크플로를 유지관리하는 대신 문서 부분에 집중할 수 있도록 훨씬 더 간소화되고 효율화될 수 있습니다.