tech docs

gov.uk 하나의 로그인 기술 문서

이 repo에는 정부 부서의 기술자가 Gov.uk One Login에 탑승하는 데 도움이되는 문서가 포함되어 있습니다. 기술 문서 템플릿을 사용하여 게시됩니다.

콘텐츠 변경

Gov.uk One Login Technical Writing Team 은이 문서를 소유하고 있으며 콘텐츠 변경 승인에 대한 책임이 있습니다. 사용자 중심으로 작성되었으며 GDS 컨텐츠 표준을 충족합니다. 이는 다음을 의미합니다.

• 컨텐츠 계획, 쓰기 및 관리에 대한 Gov.uk 지침
• gov.uk 스타일 가이드
• Gov.uk 기술 스타일 가이드
• 다른 명확한 글쓰기 원칙

Gov.uk One 로그인에서 일하는 경우, 컨텐츠 변경에 대한 도움을 받으려면 기술 작문 팀에 문의하여 작고 사용자 행동에 영향을 미치지 않는 한 도움을 청하십시오.

작은 콘텐츠 변경 사항은 다음과 같습니다.

• 이해를 향상시키기 위해 설명을 추가합니다
• 코드 샘플 수정
• 깨진 링크 또는 오타 수정

이러한 변경 사항을 직접 수행 한 다음 풀 요청에 대한 기술 작가 검토를 요청할 수 있습니다. 변경 사항이 작은 지 확실하지 않으면 #Di-Technical Writing Slack 채널로 문의하십시오.

기술적 인 변화

오케스트레이션 팀은 Tech Docs 플랫폼의 유지 보수 및 운영 건강을 담당합니다. 해당 공간의 변경 승인을 받으려면 상담해야합니다.

예제는 다음과 같습니다.

• GitHub 액션 워크 플로 변경
• AWS 배포 또는 빌드 인프라 변경
• 종속성 업데이트
• 컨텐츠를 변경하지 않는 루비 업데이트

문서 변경을 미리보십시오

브라우저의 문서에 대한 변경 사항 및 추가 사항을 미리 보려면이 리브리로 복제 하고이 리브레의 Dockerfile을 사용하여 루비를 로컬로 설정하지 않고도 머신에서 미들먼 서버를 실행하십시오.

이 설정에는 Live Reload가 활성화되어 있으므로 소스 디렉토리에서 파일을 편집 할 때 변경 사항이 적용됩니다. 이에 대한 유일한 예외는 config/tech-docs.yml 을 변경하는 경우 미리보기의 변경 사항을 확인하려면 서버를 중지하고 다시 시작해야합니다. Ctrl-C 로 서버를 중지 할 수 있습니다.

도우미 스크립트 실행 :

./preview-with-docker.sh

Docker 컨테이너를 제작하는 데 몇 분이 걸릴 수 있습니다. 특히 스크립트를 처음 실행 한 경우. 서버가로드를 완료하면 터미널에서 다음 출력이 표시되어야합니다.

== View your site at " http://localhost:4567 " , " http://127.0.0.1:4567 "
== Inspect your site configuration at " http://localhost:4567/__middleman " , " http://127.0.0.1:4567/__middleman " /usr/local/bundle/gems/tilt-2.0.11/lib/tilt/redcarpet.

다이어그램을 변경합니다

다이어그램은 내용이므로 변경하면 기술 작문 팀에게 리뷰를 요청해야합니다.

Draw.io Desktop 앱을 설치하고 사용하여 source/images/originals 폴더에서 Draw.io 파일을 편집 할 수 있습니다.

다이어그램 당 하나의 draw.io 파일을 사용하십시오.

Draw.io 데스크탑 앱 설치

다음 명령을 실행하여 명령 줄에서 graw.io 데스크탑 앱을 사용하십시오.

 brew install --cask drawio
alias draw.io='/Applications/draw.io.app/Contents/MacOS/draw.io'

다이어그램 편집 및 게시

다음 단계를 따르십시오.

1. draw.io를 사용하여 다이어그램을 작성하고 수정하십시오.
2. draw.io 파일을 source/images/originals 폴더에 저장하십시오.
3. 다이어그램을 확장 가능한 벡터 그래픽 (SVG)으로 게시하십시오.
4. svg 파일을 source/images 폴더에 저장하십시오.

유용한 명령

다이어그램 업데이트 :

 draw.io source/images/originals/top-level-technical-diagram.drawio

다이어그램의 SVG 버전을 생성하고 source/images/originals 폴더에 저장하십시오.

 draw.io -x -o source/images/top-level-technical-diagram.svg source/images/originals/top-level-technical-diagram.drawio

draw.io -x -o source/images/technical-flow-diagram.svg source/images/originals/technical-flow-diagram.drawio

하나의 로그인 기술 문서를 gov.uk 라인

이 저장소는 Vale 및 GDS Tech Docs Linter Ruleset을 사용합니다.

로컬 컴퓨터에 Linter를 설치합니다

당신은 필요합니다 :

• 홈브류를 설치하십시오
• 베일을 설치하십시오

코드 편집기로 줄을 서십시오

많은 코드 편집기는 문서를 업데이트 할 때 오류가 발생할 수있는 Vale 용 확장자 또는 플러그인을 제공합니다. 로컬 컴퓨터에 여전히 베일이 설치되어야합니다.

Vale Command Line 인터페이스 (CLI)로 줄이

기본적으로 Vale은 --config 플래그에 경로를 제공하지 않는 한이 구성 파일과 동일한 디렉토리에서 실행해야합니다. Vale Cli를 사용하여 Linter를 실행하려면 :

1. 터미널 창에서 repo로 이동하십시오.
2. vale sync 실행하여 최신 Tech-Docs-Linter 패키지를 다운로드하고 구성 파일에 나열된 StylesPath 에이를 압축하십시오.
3. 명령 vale . 전체 repo에 보풀을 보풀을 보거나 해당 디렉토리 만 감금하는 디렉토리로가는 경로를 제공하려면 예 : vale ./source/go-live

최신 기술 문서 리터 규칙 세트 업데이트

Tech Docs Linter Ruleset에 새 규칙이 추가되면 준비가되면이 리포지토리에서 사용한 패키지를 업버로 변환 할 수 있습니다. 이후 버전의 규칙 세트는 다음과 같이 테스트하고 추가 할 수 있습니다.

1. 지점을 만듭니다.
2. Vale 구성 파일에서 패키지 버전 번호를 업데이트하십시오.
3. vale sync 실행하여 최신 패키지를 다운로드하고 압축 해제하십시오.
4. vale ./source 실행하여 Linter를 테스트하십시오.
5. 새로운 규칙 세트가 발생하는 변경 사항을 수정하십시오 (바람직하게는 각 규칙 위반에 대해 하나의 커밋).
6. Vale Config 파일의 최신 버전 번호로 PR을 올리십시오.

행동 강령

alphagov 행동 강령을 참조하십시오.

특허

달리 명시되지 않는 한 Codebase는 MIT 라이센스에 따라 릴리스됩니다. 여기에는 Codebase와 Documentation의 샘플 코드가 모두 포함됩니다.

문서는 © Crown Copyright이며 Open Government 3.0 라이센스의 조건에 따라 제공됩니다.