둘러보기 작성 가이드

사용자가 프로젝트에 효과적으로 익숙해 지도록 콘텐츠를 둘러보기 양식으로 가장 잘 보여주는 몇 가지 가이드라인은 다음과 같습니다.

Cloud Shell 기능

  • 전용 레이아웃: 둘러보기는 Google Cloud Console의 오른쪽에 있는 사이드 패널(폭 310픽셀)에 표시됩니다.
  • 탐색: 사용자는 '계속' 및 '뒤로' 버튼을 사용하여 둘러보기를 이동할 수 있습니다. 참고로, 재방문한 단계를 넘어가는 버튼은 '계속'이 아니라 '앞으로'입니다. 사용자는 '가이드 취소'를 통해 둘러보기를 종료하고 나중에 그만둔 곳에서 다시 시작할 수도 있습니다.
  • 남은 코드: 둘러보기에 코드 스니펫을 포함할 수 있습니다. 인라인 아이콘 복사 아이콘을 사용하면 사용자가 이 스니펫을 Cloud Shell에 직접 붙여넣을 수 있도록 코드 형식으로 지정됩니다.

둘러보기가 시작된 Console 세션

오른쪽에 둘러보기 창이 열려 있는 Console 세션입니다. 사용자는 인라인 아이콘을 사용하여 코드를 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분

    **선행 조건**: GCP 계정

    다음 단계로 이동하려면 **계속** 버튼을 클릭하세요.

  • 배경 페이지

    • 상황 설명: 둘러보기를 작성할 때 상황에 맞는 설명을 제공하는 것이 유용한 경우가 많습니다. 짧은 제품 개요를 제공하거나 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))를 포함하세요.
    • 스크린샷에서 스포트라이트 사용: 콘솔에서 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/walkthrough-markdown-reference)를 참조하세요.

    **뒷마무리하는 것을 잊지 마세요**: 테스트 프로젝트를 만든 경우에는 불필요한 청구를 피하기 위해 삭제해야 합니다. `gcloud projects delete <PROJECT-ID>`를 사용하세요.