Linux Foundation 프로젝트

이 페이지에는 Google Season of Docs에서 수락된 기술 작문 프로젝트의 세부정보가 포함되어 있습니다.

프로젝트 요약

오픈소스 조직:
Linux Foundation
테크니컬 라이터:
보론
프로젝트 이름:
문서 호스팅 및 생성과 재구성 시작 페이지와 개발자 가이드를 재작업합니다.
프로젝트 기간:
표준 기간 (3개월)

Project description

개요 :

문서는 최종 사용자와 개발자의 제품 또는 서비스 사용을 지원하기 위해 마련되었습니다. 좋은 문서는 사용자가 소프트웨어 사용 방법, 기능, 도움말, 유용한 정보를 배우고 소프트웨어 사용 중 발생하는 일반적인 문제를 해결할 수 있는 방법을 제공하기 때문에 매우 중요합니다. 또한 지원 비용을 절감해 주며 제품의 기업 및 오픈소스 아이덴티티의 일부이기도 합니다. 좋은 문서화는 제품과 개발팀의 건전성을 보여주는 지표입니다.

좋은 문서가 없으면 사용자는 위의 작업을 효과적이고 효율적으로 수행하는 방법을 모를 수 있습니다. 문서는 제품의 성공을 보장하는 데 중추적인 역할을 할 수 있습니다. 좋은 커뮤니케이션은 항상 모든 비즈니스 또는 제품의 중심에 있고, 훌륭한 문서는 이러한 커뮤니케이션을 누구나 성공할 수 있도록 액세스할 수 있는 관리 가능한 프레임워크로 만들어 주기 때문입니다.

AGL과 같은 조직에서는 모든 문서 사이트에 양질의 빌드 및 호스팅 워크플로 파이프라인이 필요하며, 여러 버전과 많은 자세한 문서가 포함되어 있습니다. 문서 파일 (마크다운)은 여러 저장소에 분산되어 있어 유지관리 및 업데이트 작업이 매우 복잡하고 시간이 많이 소요됩니다.

현재 상태 :

  • AGL 문서 웹사이트는 다양한 저장소에서 가져온 마크다운 파일 모음을 기반으로 합니다.
  • 문서 페이지는 현재 코르도바 프로젝트의 엔진을 사용하여 마크다운으로 개별 소스 내에 호스팅됩니다.
  • 이렇게 하면 문서 빌드 및 호스팅 프로세스에 4개의 저장소 설정이 적용됩니다.
  • Docs-webtemplate[https://github.com/automotive-grade-linux/docs-webtemplate] : Jekyll 웹사이트 템플릿이 포함되어 있습니다.
  • Docs 도구[https://github.com/automotive-grade-linux/docs-tools] : 마크다운 파일에서 기술 웹사이트를 자동으로 생성하는 도구가 포함되어 있습니다.
  • Docs 소스[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]에 있는 fetch_files.yml에 따라 모든 마크다운 파일을 수집하고 템플릿을 만듭니다.
  • 어글리 문서 웹사이트 생성의 현재 워크플로 : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
  • section_version.yml에는 모든 도서 yaml 파일에 대한 링크가 포함되어 있으며 원격 저장소에서 모든 도서 yaml 파일을 docs-webtemplate[https://github.com/automotive-grade-linux/docs-webtemplate]으로 가져옵니다. Book yaml 파일에는 원격 저장소의 마크다운 파일로 연결되는 모든 URL이 포함됩니다.
  • 모든 마크다운 파일을 가져오는 즉시 이에 따라 배포되는 docs-gh-pages[https://github.com/automotive-grade-linux/docs-gh-pages] 에서 AGL 문서 웹사이트를 생성하는 도구 프로세스가 있습니다.
  • 파이프라인을 유지보수하는 현재 프로세스는 특히 신규 기여자에게 사용자 및 개발자 친화적이지 않습니다. 이 워크플로 파이프라인 (빌드 및 호스팅)은 개발자가 문서 생성 및 배포 워크플로를 유지 관리하는 대신 문서 부분에 집중할 수 있도록 훨씬 간소화되고 간소화될 수 있습니다.