web-dev-qa-db-ja.com

あいまいな状況につながるスタイルに対処するにはどうすればよいですか？

テキストがあいまいになる可能性のあるスタイルルールの小さなセットがあります。これは通常、本では問題ではありませんが、あいまいさは大した問題ではありませんが、技術文書では問題になる可能性があります。

そのような規則の1つは、完全なポイントとコンマは、閉じ引用符の前に置く必要があるということです。

米国の慣例では、コンマと完全なポイントは、引用資料の一部であるかどうかに関係なく、閉じ引用符の内側に設定されます。

Waddingham、A.（2014）、New Hart's rules：The Oxford style guide、p。 163。

ときどき、技術文書を書くときに、あいまいさを避けるためにこの規則に明らかに違反しました。たとえば、代わりに：

ブロック「M +」、「TX」、および「B-」を表示するには、パスワード「Ge：sa＃zsY3OMEb、cBXqw-5h/0Z」を使用して、サービスアカウント「cron1」で認証します。

私は書きます：

ブロック「M +」、「TX」、および「B-」を表示するには、パスワード「Ge：sa＃zsY3OMEb、cBXqw-5h/0Z」を使用して、サービスアカウント「cron1」で認証します。

それ以外の場合、ほとんどのユーザーは単にパスワードをコピーしますドット付きで、なぜそれが機能しないのかわかりません。つまり、アカウント名についてはあいまいさはありませんが、ブロックの名前に関してはためらう可能性があります。

時々ルールに違反し、他のルールに従うことは、私には理想的な解決策のようには思えません。

  • それは矛盾しています。
  • それは間違っているようです。それを読んだとき、わざとルールに違反したことを思い出さなければなりません。
  • 基本的なスタイルのルールを盲目的にたどるのではなく、私に考えさせられます。

より良い解決策はありますか？

typographystyleambiguity
2
Arseni Mourzenko

可能な場合はコードスタイルを使用する

認められた基準に従うことは、しばしばUXで繰り返されるアドバイスであり、これは例外ではありません。

開発者とソフトウェアエンジニアは、コードを表示するスタイルに慣れています。それらは、頻繁に参照するドキュメントによく見られるためです。

  • ブートストラップenter image description here
  • Vue.jsList item
  • O'Reilly Books（Python）enter image description here
  • スタックオーバーフロー（Java）

enter image description here

各例には、ドキュメントテキスト内にコードテキストのブロックと単一の単語/フレーズの両方が含まれています。 （O'Reillyの本の例ではMultiSelectです。）

典型的なコード表示パターンには、

  • 等幅フォント
  • 文字色処理
  • 背景色（通常は灰色）
3
Benjamin S