ההנחיות הבאות יעזרו לכם להציג את התוכן שלכם בצורה של הדרכה, כדי שהמשתמשים יוכלו להכיר את הפרויקט שלכם בצורה יעילה.
תכונות של Cloud Shell
- פריסה ייחודית: הדרכות מוצגות בחלונית צדדית בצד שמאל של Google Cloud המסוף.
- ניווט: המשתמשים יכולים לעבור בין השלבים במדריך באמצעות הכפתורים הבא והקודם בכל שלב. הם יכולים גם לסגור את המדריך ולהמשיך מהמקום שבו הם הפסיקו.
- קוד מוכן להפעלה: אפשר להעתיק קטעי קוד ישירות אל Cloud Shell.
סשן של Cloud Shell Editor עם חלונית של מדריך פתוחה. המשתמשים יכולים להעתיק קוד ישירות אל Cloud Shell בלחיצה על לחצן, ולעבור בין דפים באמצעות הלחצנים הבא והקודם.
סגנון כתיבה
- שומרים על טון קליל: המדריכים צריכים להיות אינפורמטיביים ומועילים, אבל לא רשמיים מדי.
- אתם, המשתמשים: השתמשו בלשון פנייה (כן: אתה, את, שלכם, שלך; לא: אנחנו, אני, שלנו וכו')
- הסבר על סיבה ותוצאה: כשמבקשים מהמשתמשים לבצע שלב מסוים, חשוב להסביר את ההיגיון מאחורי הפעולה ואת התוצאה הצפויה.
- הגדרת יעדים ממוקדים: לפני שכותבים את התוכן של ההדרכה, חשוב להגדיר יעד ברור שרוצים שהמשתמשים ישיגו. חשוב לזכור את המטרה הזו כשיוצרים את ההדרכה.
| מקורי | הנתונים המעודכנים | שיפור |
| בדף הבא נסביר איך ליצור מדריך חדש. | לוחצים על המשך כדי לעבור לשלב הבא ולהתחיל בהגדרת המדריך. | התמקדות במשתמש; שימוש בניסוח פעיל
שימוש בשפה לא רשמית |
| מריצים את הפקודה הבאה:
``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ``` |
כדי להציג רשימה בטבלה של כל הפרויקטים ומספרי המזהים שלהם, עם הכותרת 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
לוחצים על הלחצן **המשך** כדי לעבור לשלב הבא.
דף רקע
- הגדרת הסצנה: כשכותבים מדריך, כדאי לספק הקשר. יכול להיות שתצטרכו לספק סקירה כללית קצרה של המוצר או להציג במהירות את התכונות הבולטות של ממשק המשתמש.
דוגמה ## מה זה 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 , כדי שהמשתמשים יוכלו לזהות את הרכיבים בלי לחפש תמונה.
- תצוגה חלופית: אם אפשר, כדאי לספק קישור לתוכן ההדרכה שלכם שמוצע כתוכן סטטי. כך המשתמשים יכולים לבחור איך לצרוך את המידע שאתם מספקים.
- טיפים יתקבלו בברכה: במקומות שבהם זה רלוונטי, כדאי להוסיף טיפים (שמסומנים ב-**Tip:**) כדי לספק למשתמשים פתרונות אינטואיטיביים יותר ושיטות מומלצות.
דוגמה ## כתיבה ב-Markdown
כדי לכתוב את ההדרכה, צריך להשתמש ב- [Markdown](https://en.wikipedia.org/wiki/Markdown) ולפעול לפי ההנחיות הבאות:
### עריכת השם
משנים את הכותרת של המדריך הזה (# Introduction to writing tutorials in Cloud Shell) לכותרת הבאה:
```
# למד אותי איך לכתוב מדריך
```
### הוספת שלב חדש
לאחר מכן, מוסיפים שלב מיד אחרי הכותרת, כך:
```
## שלב 1
זהו שלב חדש שהוספתי עכשיו.
```
כל 'שלב' במדריך מוצג בדף אחד.
**טיפ**: כדי לעבור בין השלבים, המשתמשים ילחצו על הלחצנים 'הקודם' ו'המשך/הבא'.
סיכום
- ברכות: חשוב להוסיף סמל של גביע (<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>) כדי להביע הערכה למשתמשים שהקדישו זמן כדי לסיים את המדריך.
- סיכום: סיכום של לקחים חשובים שאתם רוצים שהמשתמשים ילמדו מההדרכה.
- מה עושים עכשיו: כדי לעזור למשתמשים להתקדם בתהליך, כדאי לספק להם שלבים הבאים – אלה יכולים להיות המלצות לקריאה, משאבים נוספים או אפילו מדריך נוסף.
- חשוב לשים לב למשתמשים: מומלץ להנחות אותם למחוק את כל משאבי הבדיקה שהם יצרו לצורך המדריך, כדי למנוע חיובים לא רצויים.
דוגמה ## Congratulations
<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>
סיימת!
עכשיו המשתמשים יכולים להפעיל את המדריך ב-Cloud Shell ולהתחיל להשתמש בפרויקט בקלות.
רשימה מלאה של כלים לכתיבת הדרכות ב-Cloud Shell זמינה במאמר [Tutorial Markdown Reference](https://cloud.google.com/shell/docs/tutorial-markdown-reference).
**אל תשכחו לנקות אחריכם**: אם יצרתם פרויקטים לצורך בדיקה, הקפידו למחוק אותם כדי להימנע מחיובים מיותרים. משתמשים בפקודה `gcloud projects delete <PROJECT-ID>`.