نظرة عامة
يقدّم هذا الدليل إرشادات عامة لكتابة برامج تعليمية خاصة بك حول Google Earth Engine. يهدف هذا الدليل إلى تسهيل إنشاء برامج تعليمية عالية الجودة تتسم بالوضوح والإيجاز وسهولة الفهم لجميع أفراد منتدى Earth Engine.
نماذج الأدلة التعليمية أدناه هي أيضًا دليل إضافي لمساعدتك في بدء إنشاء أدلتك التعليمية. يمكن العثور على تفاصيل حول كيفية استخدام النماذج للبدء في كتابة دليل تعليمي.
بالإضافة إلى ذلك، يوفّر دليل أسلوب البرامج التعليمية في منتدى Google Cloud مرجعًا قيّمًا لكتابة برامج تعليمية شاملة لجمهور واسع، بينما يوضّح دليل أسلوب Google JavaScript الأسلوب المقترَح لاستخدامه في عينات التعليمات البرمجية بلغة JavaScript. قد يشير المراجعون إلى هذه الأدلة عند مراجعة ما ترسله.
الإرشادات العامة
- كن موجزًا.
- لا تكرّر نفسك.
- لا تكرّر العبارة نفسها (حتى لو كانت صياغتها مختلفة).
- تحديد مستوى التقدّم بشكل دوري
- أدرِج صورًا ونصًا في النقاط الرئيسية في البرنامج التعليمي ليعرف المستخدم أنّه يسير على المسار الصحيح. يُنصح باستخدام هذه الفئة باعتدال.
- استخدِم صيغة المعلوم كلما أمكن.
- "عندما يغيّر المستخدم القيمة"، وليس "عندما تتغيّر القيمة".
- Exception: It's okay to use passive voice when you'd have to go out of your way to use active voice, or if the actor is obvious or not relevant ("an animated GIF is returned" instead of "Earth Engine returns an animated GIF").
- التزِم بالوقائع.
- تجنَّب استخدام صيغ المبالغة ("هذه هي الطريقة الأفضل والأسرع بنسبة%100").
- تجنَّب الترويج لمنتجات أو خدمات.
- تجنَّب المواضيع المثيرة للجدل.
- يجب تضمين الاقتباسات وعناوين URL عند الإشارة إلى طرق ومجموعات بيانات وتحليلات معيّنة.
- أنشئ برنامجًا تعليميًا مستقلاً.
- يُرجى عدم الاعتماد على مكتبات خاصة خارج واجهة برمجة التطبيقات أو مجموعات بيانات غير متوفّرة في كتالوج بيانات Earth Engine العام.
- إذا كنت تقدّم بيانات أو خوارزميات إضافية، لا تشاركها إلا إذا كان لديك إذن بذلك. ويجب تضمين جميع التراخيص ومصادر المحتوى المطلوبة.
- اختبِر الرمز.
- تأكَّد من تشغيل واختبار جميع عيّنات التعليمات البرمجية المضمّنة قبل إرسال مقالتك للمراجعة مباشرةً.
رؤوس ملفات الدليل التعليمي
إذا كنت تنشئ أدلة تعليمية للمنتدى وترسلها يدويًا بدون استخدام النماذج المقدَّمة في كتابة دليل تعليمي، عليك إضافة البيانات الوصفية المناسبة ورأس الترخيص يدويًا إلى بداية الملف. اختَر التنسيق المطلوب لعرض نموذج يمكن نسخه في البرنامج التعليمي الخاص بك:
Markdown
أضِف ما يلي إلى بداية المستند. يجب ألا تسبق أي مسافة بيضاء أو أحرف أخرى العنوان:
---
title: Your tutorial title
description: A short description of the tutorial, all on one line with no carriage returns.
author: your-github-username
tags: comma-separated, lowercase, list, of, related, keywords
date_published: YYYY-MM-DD
---
<!--
Copyright 2023 The Google Earth Engine Community Authors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
تأكَّد من استبدال حقول النموذج المناسبة قبل إرسال البرنامج التعليمي للمراجعة.
Colab
أضِف ما يلي إلى خلية رمز برمجي في بداية دفتر الملاحظات:
#@title Copyright 2023 The Earth Engine Community Authors { display-mode: "form" }
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
نماذج تعليمية
Markdown
إذا كنت على دراية بـ git وGitHub، يمكنك استخدام الرمز أدناه كنموذج للبدء:
---
title: Your tutorial title
description: A short description of the tutorial, all on one line with no carriage returns.
author: your-github-username
tags: comma-separated, lowercase, list, of, related, keywords
date_published: YYYY-MM-DD
---
<!--
Copyright 2023 The Google Earth Engine Community Authors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
In a few sentences, describe what the user is going to learn. Be sure to include
_concise_ background information; only include what's helpful and relevant.
When in doubt, leave it out!
## Section heading 1
Break up your tutorial into manageable sections.
With one or more paragraphs, separated by a blank line.
Inside your sections, you can also:
1. Use numbered lists
1. ..when the order..
1. ..of items is important.
And:
- This is a bulleted list.
- Use bulleted lists when items are not strictly ordered.
..and even:
Use | tables | to organize | content
------- | -------- | ----------- | -------
Your | tables | can | also
contain | multiple | rows | ...
## Section heading 2
Use separate sections for related, but discrete, groups of steps.
Use code blocks to show users how to do something after describing it:
```js
// Use comments to describe details that can't be easily expressed in code.
// Always try making code more self descriptive before adding a comment.
// Similarly, avoid repeating verbatim what's already said in code
// (e.g., "assign ImageCollection to variable 'coll'").
var coll = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA');
```
### Use subsections if appropriate
Consider breaking longer sections that cover multiple topics or span multiple
pages into subsections.
بدلاً من ذلك، يمكن فتح النموذج أعلاه مباشرةً في محرِّر الملفات المستند إلى الويب في GitHub من خلال اتّباع التعليمات الواردة في مقالة كتابة دليل تعليمي.
احرص على الرجوع إلى كتابة دليل تعليمي للحصول على تفاصيل مهمة حول كيفية اقتراح الأدلة التعليمية وتأليفها وإرسالها.
Colab
لإنشاء ورقة ملاحظات Colab جديدة باستخدام نموذج النمط المقترَح، انقر هنا:
سيؤدي ذلك إلى فتح دفتر ملاحظات يحتوي على تعليمات حول تأليف دليلك التوجيهي وإرساله. يُرجى الرجوع إلى كتابة برنامج تعليمي للحصول على تفاصيل مهمة حول الاقتراح والتأليف وعملية الإرسال.