今年も始まりました Salesforce Platform Advent Calendar。骨太なネタは後に書く人に任せて、軽めのネタを書きたいと思います。
Salesforce の開発者向けドキュメントは充実している
開発をしていく中で絶対に使うであろうドキュメント。Java や Python などといった言語でもライブラリは充実していて、基本的なことはそこを見れば書いてあります。
言語だけでなくOSやミドルウェアでもそれは同じ。実装をしていく中で詰まる箇所があればまず最初に公式ドキュメントを見るという人も一定数いるはず。
Salesforce でもそれは同じで、以下のサイトにはたくさんの公式ドキュメントがあります。
Salesforce の開発で使用する言語は特殊な面もありますが、言語の基本的なドキュメントは日本語に翻訳されているのでなんとか開発を進められます。
ドキュメントの一例
- Apex 開発者ガイド
- Force.com REST API 開発者ガイド
- Force.com SOQL および SOSL リファレンス
- Force.com 移行ツールガイド
- Salesforce および Force.com のオブジェクトリファレンス
- Visualforce 開発者ガイド
意外なところで使うドキュメントがある
上で挙げたドキュメントはよく使うものですが、中にはちょっと変わったドキュメントもありました。
それがこちら。
[Salesforce Style Guide for Documentation and User Interface Text](Salesforce Style Guide for Documentation and User Interface Text)
直訳すると「ドキュメントとユーザーインターフェースの Salesforce スタイルガイド」といった感じで、どうやら画面に表示させる文言なんかを決める際に参考にするドキュメントのようです。
冒頭を見るとこんなことが書いてありました。
The Salesforce Style Guide for Documentation and User Interface Text provides terminology and usage guidelines for user interface text and customer-facing documentation materials.
ドキュメントおよびユーザーインターフェイステキストの Salesforce スタイルガイドには、ユーザーインターフェイスのテキストと顧客対応のドキュメント資料に関する用語および使用方法のガイドラインが記載されています。
やはり使う用途はユーザーインターフェースだったりドキュメント資料を作る際の参考資料の模様。
さらに中を読み進めていくとこんなことが書いてあります。
Abbreviations
In general, abbreviated terms are repeated often or appear in tables or other tight spaces.
Don't confuse your reader with too many abbreviations or too much jargon. When in doubt, spell out the term.
略語
一般に、省略された用語は頻繁に繰り返されるか、テーブルや他のタイトなスペースに現れます。
あまりにも多くの略語や専門用語で読者を混乱させないで下さい。不確かな場合は、その用語を記入してください。
Capitalization
- When spelling out an acronym, only capitalize the individual words if they're proper nouns. Use all capital letters for the acronym itself.
- Use all lowercase for file extensions. For examples, see File Names and Extensions.
- Don't alter the capitalization of abbreviations in titles. For examples, see Capitalization.
- Use uppercase to document time. For examples, see AM, PM.
- If an acronym is read as alphabetic letters, choose the article according to the first letter. For example: an API, a URL.
大文字
- 頭字語のスペルを記入するときは、固有名詞であれば個々の単語を大文字にします。頭字語自体にはすべて大文字を使用してください。
- ファイル拡張子にはすべて小文字を使用してください。例については、「ファイル名と拡張子」を参照してください。
- タイトルの略語の大文字を変更しないでください。例については、「資本化」を参照してください。
- 大文字を使用して時間を記録します。例については、AM、PMを参照してください。
- 頭字語がアルファベットの文字として読み取られた場合は、最初の文字に従って記事を選択します。たとえば、API、URLなどです。
他にも色々あったのですが長かったので割愛しますが、中身は思った以上に事細かに項目と避けるべきやり方や推奨するやり方が記載されています。
伝わりやすさを考えるきっかけになる
中を見て見ると至極当たり前の内容も多いですが、自分の場合だと開発をしていく中でついうっかり分かりにくい言葉を使ってしまうことがあるので、その辺を注意する意味でも使えると思いました。
業務システムでは使う人が迷わないことも重要なので、開発の中に取り入れてみると分かりやすいUIを実装する手助けになると思います。
とまあ取り留めのない文章になってしまいましたが、開発の時に心の片隅に置いておくといいことある.....かも。
これ以外にもたくさんのドキュメントや開発者向けリソースがあるので、探してみるとまた面白いものがありそうです。
日本語になっていない......それはSalesforce中の人に頑張ってもらいましょう！！！
以上 Salesforce Platform Advent Calendar 2017 1日目の投稿でした。