이 페이지에는 Google Season of Docs에 선정된 기술 문서 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 구성:
- Linux 재단
- 기술 문서 작성자:
- 붕소
- 프로젝트 이름:
- 문서 호스팅 및 생성을 수정하고 시작 페이지 및 개발자 가이드를 재구성합니다.
- 프로젝트 기간:
- 표준 기간 (3개월)
Project description
개요 :
문서는 최종 사용자와 개발자가 제품 또는 서비스를 사용하는 데 도움을 주기 위해 작성되었습니다. 우수한 문서는 사용자가 소프트웨어 사용 방법, 기능, 도움말, 요령을 학습하고 소프트웨어 사용 시 발생하는 일반적인 문제를 해결할 수 있는 수단을 제공하므로 매우 중요합니다. 또한 지원 비용을 줄이고 제품의 기업 및 오픈소스 ID의 일부가 됩니다. 우수한 문서는 제품과 개발자팀의 건전성을 보여주는 신호입니다.
문서가 제대로 작성되어 있지 않으면 사용자가 위 작업을 효과적이고 효율적으로 수행하는 방법을 알지 못할 수 있습니다. 문서는 제품의 성공을 보장하는 데 핵심적인 역할을 할 수 있습니다. 훌륭한 커뮤니케이션은 모든 비즈니스 또는 제품의 핵심이며, 훌륭한 문서는 이러한 커뮤니케이션을 모든 사람이 성공을 위해 액세스할 수 있는 관리 가능한 프레임워크에 두기 때문입니다.
모든 문서 사이트에는 우수한 빌드 및 호스팅 워크플로 파이프라인이 필요합니다. 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] : Markdown 파일에서 기술 웹사이트를 자동으로 생성하는 도구가 포함되어 있습니다.
- 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] : 문서 사이트용 GitHub 페이지 저장소를 배포했습니다[https://gist.github.com/growupboron/docs.automotivelinux.org].
- 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 문서 웹사이트를 생성하는 도구 프로세스가 실행되고 이에 따라 배포됩니다.
- 파이프라인을 유지보수하는 현재 프로세스는 특히 신규 참여자를 대상으로 사용자와 개발자 친화적이지 않습니다. 이 워크플로 파이프라인 (빌드 및 호스팅)은 개발자가 문서 생성 및 배포 워크플로를 유지관리하는 대신 문서 부분에 더 집중할 수 있도록 간소화되고 간소화된 방식으로 이루어질 수 있습니다.