다음 가이드라인은 사용자가 프로젝트를 효과적으로 익힐 수 있도록 콘텐츠를 튜토리얼 양식으로 제공하게끔 도와줍니다.
Cloud Shell 기능
- 고유한 레이아웃: 튜토리얼은 Google Cloud Console 오른쪽의 측면 패널에 표시됩니다.
- 탐색: 사용자는 각 단계에서 다음 및 이전 버튼을 사용하여 튜토리얼을 탐색할 수 있습니다. 또한 튜토리얼을 종료하고 그만둔 곳에서 다시 시작할 수도 있습니다.
- 남은 코드: 코드 스니펫은 Cloud Shell에 직접 복사할 수 있습니다.
튜토리얼 창이 있는 Cloud Shell 편집기 세션이 열립니다. 사용자는 버튼을 클릭하여 코드를 Cloud Shell에 직접 복사하거나 다음 및 이전 버튼을 사용하여 페이지 간에 이동할 수 있습니다.
작성 스타일
- 딱딱하지 않게: 튜토리얼은 유익한 정보를 제공해야 하지만 어투가 지나치게 정중해서는 안 됩니다.
- 귀하, 사용자: 2인칭 대명사를 사용합니다(적합한 표현: 귀하, 귀하의, 적합하지 않은 표현: 우리, 나, 우리의 등).
- 원인 및 영향 설명: 사용자에게 특정 행동을 하도록 요구할 경우, 그렇게 하는 이유와 그 행동이 가져올 결과를 설명합니다.
- 목표에 집중: 튜토리얼 콘텐츠를 작성하기 전에 사용자가 달성해야 할 명확한 목표를 설정합니다. 이 목표를 염두에 두고 튜토리얼를 작성합니다.
| 원본 | 수정본 | 개선 |
| 다음 페이지에서는 새 가이드를 만드는 방법을 배우게 됩니다. | 다음 단계로 계속 진행하여 가이드 설정을 시작해 보세요. | 사용자에게 초점을 맞추고 적극적인 어투 사용
편안한 표현 사용 |
| 다음 명령을 실행합니다. ``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ``` |
모든 프로젝트와 해당 ID 번호를 'Projects'라는 표 형식의 목록으로 표시하려면 다음 명령을 실행하세요. ``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ``` | 결과를 예상할 수 있도록 이유를 미리 설명 |
Let's get started!
|
Let's get started!
이 가이드는 대화형 튜토리얼을 직접 만드는 방법을 보여줍니다. 완성된 튜토리얼을 사용자가 시작하는 데 사용할 수 있는 버튼을 생성하는 방법도 안내합니다. |
가이드에서 다루는 내용의 명확한 로드맵 콘텐츠를 작성할 때 집중력을 유지해야 합니다! |
권장사항
짧게: 튜토리얼 창의 전용 공간 제약으로 인해 사용자에게 한 번에 표시할 수 있는 정보 양이 제한되어 있습니다. 한눈에 보기 어렵고 세로 스크롤이 필요한 대량의 텍스트는 사용하지 않는 것이 좋습니다. 바이트 크기 단위로 정보를 제공하는 것이 좋습니다.
한 페이지에서 5개의 단계와 3개의 코드 스니펫이 넘지 않도록 합니다.
단락은 5줄 이하가 이상적이며 한 가지 개념만 다뤄야 합니다.
페이지가 길어지는 경우에는 창 길이의 최대 두 배까지로 제한합니다.
코드 및 터미널 블록은 읽을 수 있을 정도로 작아야 합니다.
- 10줄 이하를 목표로 합니다.
- 가로 스크롤을 줄이기 위해 한 줄당 80자 이하를 목표로 합니다.
- 사용자가 대량의 복사-실행을 수행할 필요가 없도록 다중 명령 코드 블록을 피합니다.
소개 페이지: 튜토리얼을 소개와 함께 시작합니다.
- 기대치 설정: 사용자가 이 튜토리얼을 완료함으로써 어떤 이익을 얻을 수 있는지를 간략하게 설명합니다.
- 예상 소요 시간: 사용자가 튜토리얼에 어느 정도의 시간을 소요해야 할 것인지를 대략적으로 추정합니다. 15분 안에 마칠 수 있는 튜토리얼을 만드는 것을 목표로 하세요. 튜토리얼이 더 오래 걸리면(또는 빽빽이 채운 페이지 기준으로 15장을 넘기는 경우) 짧은 튜토리얼 여러 개로 나누는 것을 고려해야 합니다.
- 선행 정보 제공: 사용자가 중단 없이 튜토리얼을 진행하기 위해 설정해야 하는 선행 조건 리소스 또는 액세스 권한을 명확하게 밝힙니다.
예시 ## 지금 시작해 보세요.
대화형 가이드를 추가함으로써 사용자가 프로젝트를 빠르게 준비하고 실행할 수 있도록 하세요.
이 가이드에서는 이와 같은 대화형 튜토리얼을 만드는 방법을 보여줍니다. 완성된 튜토리얼을 사용자가 시작하는 데 사용할 수 있는 버튼을 생성하는 방법도 안내합니다.
**완료 시간**: 약 10분
**기본 요건**: Cloud Billing 계정
다음 단계로 이동하려면 **계속** 버튼을 클릭하세요.
배경 페이지
- 상황 설명: 튜토리얼을 작성할 때 상황에 맞는 설명을 제공하는 것이 종종 유용합니다. 짧은 제품 개요를 제공하거나 UI의 핵심 기능을 간략하게 살펴볼 수도 있습니다.
예시 ## Cloud Shell이란 무엇인가요?
시작하기 전에 Cloud Shell이 무엇을 할 수 있는지 간략하게 살펴보겠습니다.
Cloud Shell은 Google Cloud 제품용 개발자 도구가 사전 로드된 개인 호스트 가상 머신입니다. 이 대화형 셸 환경에는 내장된 코드 편집기, 영구 디스크 저장소, 웹 미리보기 기능이 포함되어 있습니다. 명령줄 액세스만 사용하려면 [console.cloud.google.com/cloudshell](https://console.cloud.google.com/cloudshell)을 방문하세요.
사용자를 Cloud Shell로 안내하여 프로젝트를 빠르게 시작하도록 돕고, 사용 사례를 알아보면서 프로젝트의 기능을 익힐 수 있는 기회를 제공할 수 있습니다.
다음 단계로 계속 진행하여 튜토리얼 설정을 시작해 보세요.
기본 예시:
- Hello World: 첫 번째 예는 긴 설명 없이도 사용자가 테스트할 수 있을 만큼 간단해야 합니다. Hello World에 상응하는 것이어야 합니다. 이 예를 기준으로 시작하여 튜토리얼에서 개념의 예를 들어보세요.
예시 ## 컨텍스트 내 가이드
현재 보고 계신 것은 컨텍스트 내 튜토리얼입니다.
튜토리얼 단계를 수행할 수 있는 Cloud Shell 환경과 함께 콘텐츠가 표시됩니다. 튜토리얼과 개발 환경을 같은 곳에 열어놓으면 사용자가 간편한 단일 화면 환경을 통해 프로젝트 사용을 쉽게 시작할 수 있습니다.
지금 명령을 실행해 보세요.
```bash
echo "Hello Cloud Shell"
```
**팁**: 코드 상자 옆에 있는 복사 버튼을 클릭하여 Cloud Shell 터미널에 명령을 붙여넣고 실행하세요.
그 다음에는 기본 튜토리얼을 작성하고 시작합니다.
튜토리얼 콘텐츠
- 신중하게 서식 지정: 텍스트 서식(굵게, 기울임꼴 등)은 집중력을 분산시킵니다. 도움이 되거나 꼭 필요할 때만 사용하세요(경고, 주요 학습 등).
- 일관된 문법: 사용자 행동을 설명할 때는 명령문을 사용하고 문장을 마침표로 마무리하세요.
- 링크 참조: 컨텍스트에 필요한 경우 사용자가 직접 조사할 수 있도록 보충 링크([링크 텍스트](링크 URL))를 포함하세요.
- 스크린샷에서 스포트라이트 사용: Google Cloud 콘솔에서 UI 요소의 위치를 강조하는 스포트라이트 기능은 사용자가 이미지를 검색하지 않고도 요소를 식별할 수 있도록 위치를 보여줍니다.
- 대체 보기: 가능한 경우에는 정적 콘텐츠 형태의 가이드 콘텐츠 링크를 제공하세요. 그러면 사용자가 제공된 정보를 사용할 것인지를 자유롭게 선택할 수 있습니다.
- 유용한 팁: 해당되는 경우 팁("**팁:**"으로 표시)을 추가하여 사용자에게 더 많은 직관적인 솔루션과 권장사항을 제공하세요.
예 ## 마크다운으로 작성
튜토리얼을 작성하려면 [마크다운](https://en.wikipedia.org/wiki/Markdown)을 사용하고 다음 가이드라인을 따르세요.
### 제목 편집
이 튜토리얼의 제목('# Cloud Shell에서의 튜토리얼 작성 소개')을 다음과 같이 변경하여 수정합니다.
```
# 가이드를 작성하는 방법을 가르쳐 주세요.
```
### 새 단계 추가
그 다음에는 제목 바로 뒤에 다음과 같은 단계를 추가합니다.
```
## 1단계
이것은 제가 방금 추가한 새 단계입니다.
```
튜토리얼의 각 '단계'가 한 페이지에 표시됩니다.
**팁**: 사용자는 '뒤로' 및 '계속/앞으로' 버튼을 사용하여 단계를 탐색할 수 있습니다.
요약
- 축하: 시간을 내어 튜토리얼을 완료한 사용자들에게 감사하다는 뜻으로 트로피 아이콘(<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>)을 추가합니다.
- 정리: 사용자들이 튜토리얼을 마치면서 기억했으면 하는 중요한 내용을 요약합니다.
- 다음 단계: 다음 단계를 제공하여 사용자의 진행 과정 전체를 돕습니다. 권장 문서, 보충 자료를 제공하거나 다른 튜토리얼을 제공할 수도 있습니다.
- 사용자에게 주의사항 전달: 원치 않는 금액이 청구되지 않도록 튜토리얼을 위해 만든 테스트 리소스를 정리할 것을 사용자들에게 안내합니다.
예시 ## 축하합니다.
<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>
설정이 끝났습니다.
이제 Cloud Shell에서 사용자들이 튜토리얼을 시작하고 프로젝트를 쉽게 사용하도록 할 수 있습니다.
Cloud Shell 튜토리얼 작성 도구의 전체 목록은 [튜토리얼 마크다운 참조](https://cloud.google.com/shell/docs/tutorial-markdown-reference)를 참조하세요.
**뒷마무리하는 것을 잊지 마세요**: 테스트 프로젝트를 만든 경우에는 불필요한 청구를 피하기 위해 삭제해야 합니다. `gcloud projects delete <PROJECT-ID>`를 사용하세요.