formatting and writing tips for method authors

21
! " # $%&&’’((( ) IBM Rational Method Composer Formatting and Writing Tips for Method Authors *+, -!!

Upload: dinhkhanh

Post on 03-Feb-2017

231 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: Formatting and Writing Tips for Method Authors

��

��

����������� ���� ����������������������������������������������� �������������������!����"�������#� ����$�������%��������� &����&''(((�����������'����'���)�� �������

IBM Rational Method Composer ������

Formatting and Writing Tips for Method Authors

�*��������+�,� ������� ��� ��

����-��������������������������!!�

Page 2: Formatting and Writing Tips for Method Authors

Formatting and Writing Tips

IBM Rational Method Composer version Page 2 of 21 ����������� ���� ����������������������������������������������� �������������������!����"�������#� ����$�������%��������� &����&''(((�����������'����'���)�� ������

���������Abstract..........................................................................................................................................................3 Text formatting, capitalization, and punctuation ............................................................................................3 ��������.������������������������������������������������������������������������������������������������������ / ,������������������������������������������������������������������������������������������������������������������ 0 1�������2������������1��$ �������������������������������������������������������������������������������������� � %�����������1��$������������������������������������������������������������������������������������������������ 3 1������������� ������ �������������������������������������������������������������������������������������� 3 $����!����������������������������������������������������������������������������������������������������������������� 4 �� ��� ������������������������������������������������������������������������������������������������������������������ 5 6��������������� ������������������������������������������������������������������������������������������������ 5 6�������������� ���������������������������������������������������������������������������������������������������

Illustrations (graphics) .................................................................................................................................10 ,����!����������������������������������������������������������������������������������������������������������������� ,��������������������������������������������������������������������������������������������������������������� 7��������������������� ��������������������������������������������������������������������������������������������

Accessibility requirements ...........................................................................................................................11 Globalization considerations........................................................................................................................11 Trademark and copyright rules....................................................................................................................12 #��������������������������������������������������������������������������������������������������������������������

Writing tips ...................................................................................................................................................14 *����������������������������������������������������������������������������������������������������������0 8���������������������������������������������������������������������������������������������������������������+ $������������������������������(��������������� �����������������������������������������������+ 9��(�(������ ���������������������������������������������������������������������������������������������3 #���!����������������!�������������������������������������������������������������������������������������������5 ������������ ����������������������������������������������������������������������������������������������������������5 *�����������(������������������������:��!���������������� ������������������������������������5 �������!�������8� ���������1��$�������� ���������������������������������������������������������5 ���������:��!�����������!��8����������������������������������������������������������������������������� ;�������� �������������������������������������������������������������������������������������������������������������

Legal notices................................................................................................................................................21

Page 3: Formatting and Writing Tips for Method Authors

Formatting and Writing Tips

IBM Rational Method Composer version Page 3 of 21 ����������� ���� ����������������������������������������������� �������������������!����"�������#� ����$�������%��������� &����&''(((�����������'����'���)�� ������

Abstract ��������������������� ��(���(���������������2��(�� ����(����������!�����������:��������������������!�������������8� ������<����������������������������������������"#,����������������=�-�������=���������������>��������!������������������� ����������������������������������������������������<1��$>�!�������!������������������������������������(��!����(����������������(��������������!���������������������������!������!��� ��������(����������������������������������(�������!�����������������!����� �����������

Text formatting, capitalization, and punctuation ������������������ ���!���������!�����������������������<1��$>��!��������������������(�����������������������������������)��:���������<-�">��!�����������������<?���������������������������������������"#,����������������=�-�������=����������������>�

Capitalization and punctuation ?��������1������������� �������,�����������.�������!����(���������������������&��!������� ��������������� �����������.������������������������������!��� �������������6����� �����!�����������.����������!����������!������!�����������������������������������������������������?���������������������������(���������!�����������.�����������������������!�!��@��������������������*��������������������������������!����������������!������!���(��2���������� �����(������������!����������������������������":�����&�8��2������������(��2�������*���A@������������2�A�(���������������������!�����������������������������(���������������2�� ������������������������(������!������������������2��������2������!������!!�������!����������":������&��

6��������������������A����������������6�!�(���������"����������(����;�;�;����A��

���2����-����������!�(�������������!����=����������8��2�=�!����������!�����������

7�����������������<'>�������������� �������������������������������� ������������� ���� �������7������������������������������������!�����!!������������������������������������������'��������

���������?��������"�����������������������������������&�• B������������2�����������(�������!����������������!�������������������������2���������"������������":�����&�����������@������������2����A�!�����������������������A�

• ":�����&�8����������������������������������������� ������������������� ���#�������������������!����������������������������(����������<�(��C�����������������(������������������ �!����(�������!�(����(�������� ��)�����������>��

*�������������������������������!�������(��������������������������������������!���������������":�����&�A��� ������2���� ����� ������������������!�������������2�A�

?��������������������������� ����������������

9��������������������������������&��

Page 4: Formatting and Writing Tips for Method Authors

Formatting and Writing Tips

IBM Rational Method Composer version Page 4 of 21 ����������� ���� ����������������������������������������������� �������������������!����"�������#� ����$�������%��������� &����&''(((�����������'����'���)�� ������

• ?����������������������6�����!����������������� ���2����������(����������������������

• ?���������������������������������������������������<D>������������������!!�����������2� ��������!��������������������������� �����������������������������������������(���������������������������1��$���������������� ������":�����&��

���E�..��������))����������������������E���F���#���!�����"����������"�������<E�"">��%���������0)����������������������������))�������������!�2���������������������!���������������������������� ���������

Fonts and type styles 7��������������:�����������������������1��$���:��� ������������������������� �������������������������<�66>�!����������������7����������������������������:������������!���������(���������8��������������!������������������ ��������������!������!��<���������������������������>��;���(������������������������������������������?������ ���� ����!�������������!������!����,����(����������������!���(���������������������!������������������������������&��

• *�������&�o ���������.����:��������������������������������� ��������������������������� �������������������������������� �������

o ,��������� ������������������������������������������������2����!����(���������������

• *��������&��o 8����������������(������������(�����������!�����������������������������(���<���������������������������!�������>��;��������������������� ����!������������������������E���� ��������������

o ,�����������!� ��2���G������������������� ����������o H������������������:��!��������������!�(�(������ ���������������!!���������������

• *���A�������!���A����A�����!���A�����<Courier New�����!���>������������������&�o ?����������������������������������������o H������!�����������������������������������!������

����(���� �����!������2������ ��������������������2��(�������������(���������2�����

Table 1. Type style and capitalization quick reference

������������ ������ ����� �����

?#������� ������� �����������

����� ��������� code font ��������

�:���<�����>&������ �:�����2� �:� ������� ��������

���������������(���� ���������������������*����(��

����������������������������� �����

�����������������*����(��

���2� �:��� ����� ��������

���������&� ��2����7�� ������ �����������

���������&���!����������������� ������� �����������

����������� ������� ��������

Page 5: Formatting and Writing Tips for Method Authors

Formatting and Writing Tips

IBM Rational Method Composer version Page 5 of 21 ����������� ���� ����������������������������������������������� �������������������!����"�������#� ����$�������%��������� &����&''(((�����������'����'���)�� ������

������������ ������ ����� �����

����2������<�� ���� ����(���>� ����� �����������

�������������<�2����������>� code font ��������

��������������<������>� code font ��������

�������:����������� code font ��������

������������� code font���������������������������������

����������@�������������2�� ����� ��������

����������������<����������>� code font ��������

����������� ����� ��������

���� ������ ��������� ������� ��������

��!�����������������:��< ������������>� �������������� ��������

����������� ������� �����������

����������<����>������ ������� ��������

��������<(����>����������� ������ ��������

��������<(����>����������� ����� ��������

����������������� ����< �����!�����������>� ������� ��������

!���������� ����� ��������

!��������� ������� ��������

!����������� ������� ��������

����������� ����� ��������

�����!�������������<�������������>� ����� ��������

2�������� ������� �����������

�� ����<�����H���>� ����� ��������������

����������!���������� ����� ��������

����� �:��� ����� ��������

������������ ����� ��������

���������� ����� ��������

���������:�� code font ��������

������������������� ������� �����������

��(������������:��< �����������!�������>� ������������� ��������

H������:��<��������&�H����&�(���AH����&A���� ���>� ���������:�� ��������������

� G����������������� ������� ��������

�������������������������!������������������ A���@�����A� ��������

��������������������!��������������� ������� �����������

����������������:��< ����!�����!���������!������������������!������:�>� ������� ��������

�����������������:� ������� ��������

������������� code font ��������

���������������� code font ��������

������ ������������ ���� ��������

����������������<��������>� ������� ��������

�������������� code font ��������

������������� ������� ����������(�������

�� ������� ����� ��������

�� ���������������� �����I����� ��J� ��������������

�� ��������������������!������������:�� ������� �����������

Page 6: Formatting and Writing Tips for Method Authors

Formatting and Writing Tips

IBM Rational Method Composer version Page 6 of 21 ����������� ���� ����������������������������������������������� �������������������!����"�������#� ����$�������%��������� &����&''(((�����������'����'���)�� ������

������������ ������ ����� �����

����������2����������� K��� ���2���L� ��������

���2�� ������� ����������(�������

�����&���!������������������� ������ ��������

�����&���!������������������� ����� ��������

��:������������������� code font ��������

*�����������<��������>� ������� ��������

����������� code font ��������

���������� ������� ����������(�������

�������!������������������������ code font ��������

����� ��������� ������ ��������

8� �����������I*-$�J� ������� ��������

(����(��������������������������� A���@�����A� ��������

(����(������������������� ������� ��������

?�������!��������6������������������(��������������������������

Hyperlinks and valid HTML ��������������������2��������� ������������������������� ���������������������������������� ���������������2��9������������������������(�����������������2�������:�&�

• *��������������������������!��������������2���������2������������&��o ������������������������<!����:�������*�������>��o �����������������������������������<�������&�*�������>�o ������������������<�������������!�����������>��

M�������������������������� ���������������(�����������!�������������!����:�����&�A?���������������� ������������N��!������������@����������A�1�(�������!�������2����������!��������!�����!������������������!�:�����&�A,����������!���������������������&�*��������O��������������������������������)��!�������:���������� �������������:���������������������!�����������������������!�����������������P�(��������������������������������������������������!������������������������!��������������������

8����������������������(�����������������:�����������������2������������������2�����������������2�������������������

• $��2�������������������������!�������������������������������������:���7���������2��� ��@�����������!��������������������2���������������������������������������:��!�����������������������������2����

• 7���������������������2��������������������������������������������2�������� ���2������������������������������������������������������� ����?���������������2����������������������������������������������<":�������!�����������������������P�����������������������)���������������������!���������������>���

• �!��������������2�������������������������2�����������������������������������������2�������������������(����������������,���������������������������!����:���������2����������������!����������������������������������(�������� ��������� ��-�!������������������������������������:���!��������������2������������(���������������������������������������������2������@������ �������!�������������������������������������������������(����������������!�����������������:���������������������(����������������

Page 7: Formatting and Writing Tips for Method Authors

Formatting and Writing Tips

IBM Rational Method Composer version Page 7 of 21 ����������� ���� ����������������������������������������������� �������������������!����"�������#� ����$�������%��������� &����&''(((�����������'����'���)�� ������

• �!�����(����������2����������������������!�������������:���!��������!������������������������������2�������������������������������!�������!�"#��� �������-�"����������������������2�������������������������������������!��������������!�������������������������������!�������!����(������1��$�!������!����������������2����������������������������(���#<anchorName>.�,����:�����&���<a class=”elementlinkwithusertext” href=”<the file and guidance info for the referenced file>.html#<anchor name>” guid=…. >Your Text</a>�

Validate the HTML ��2�����������������:����������������������2�����!�1��$�����������!��������������������������&�<p></p>.�������������2�������������!����8/�����2���%����������6�������<���&''����������(/���'>��(������2��!���������1��$���$�����A����A�������1��$�!�������������������������������������������!���������������A ���1��$A�����������������2������������������������������������� ����������!�����<������������������������>������������������������� ������������������������������������������������������������(�������� ����<��������������������� ����>������!������!������������������������:��� �������������2������������������(��������:���������������������������������������������������������������������!���)!��������1��$������������������������������������ ��� ������������!�������������������������(���� �������������)��:���������<-�">����������������������!���)!��������1��$����������������������������������1��$������<G���������:���������� ��(�������<body>�����</body>����>���������1��$��� ��!���������������N��-�"��

Headings and subheadings $���������������������������-�"�����6�������1���������������1/��6���2��������������������������������������)��(��������!����-�"���

• *���1��$�1��<1�����������>�!���������������

• *���1��$�1/�<1������/>����!������!����)��������������

• *����������������������������!��������<1/��10������1+>���

o 7���������������������������!�������o -����2�����A�����2A�(�����������������(�������!�����������!����������(�����

• 7��������� ��������������� �������<�����������������������������>���

• *��������������������������.������!�������������������� ������������������������������<���������������������!���������>�

o ����������������������o �������������6�����

• ������������!�����������������������@���������!�������������������������������� ��������

Page 8: Formatting and Writing Tips for Method Authors

Formatting and Writing Tips

IBM Rational Method Composer version Page 8 of 21 ����������� ���� ����������������������������������������������� �������������������!����"�������#� ����$�������%��������� &����&''(((�����������'����'���)�� ������

• ?�(������������������ ������(������������������(��������������������� �������������������!������������(��������:����� ��(�����

• ?���������������������(�������������� ����������������������

• *�����������!����������:������&�?������:�?��?������:����?������:����������������

List formats ����������(���������!������&��

• %��������������������������������������������(�������������� ������*��������(�����@�������������������������������!������������������!������������������������������

• $������������������������������������������*��������(�����@���������������������������!������������������ �����!�������������������������

����������&�

• *��������������������� ����(������������ ���� �����������������������2��������!�������� ���������������

• 7��������������2�����!������������������(���� ������������(������������!��� �������������������

• 7����������������������������������������������2�����������(����

• 9����������������������(�������� ���������������!��� ���������������

• -����2�����A�����2A�(������Q���������(��������������(���������������

• &�������������������(���������������*��������!������������������-�"��

• *��������������������������.�������(��������������������(��������������������� ������������������.�������(�����������������������������������

• �!�����������������������������������������������������������������������(���������:�����������������������������������������(�������������������2���������������������������

• �!�������������������������������������������������<������������!��� ��>P�����(���������������������������������

• *��������������������������������������� ����������������������������(�������!��� ���(�������� ��

• ?�����A��A�(�������������A�����A� ���������������(��2������������������������������ ����������A����A�

• ?�(���������������������(������������������(���

• 7������������������������������������(���A���!����(��&A� �������A!����(��A���������G��������#�����������!���������������A���!����(���������&A���������������������(�������!���������������������������������������������������������������,����:�����&��

������������������������G���������&�

• 7������������• ���������������������� *��)�����������

Page 9: Formatting and Writing Tips for Method Authors

Formatting and Writing Tips

IBM Rational Method Composer version Page 9 of 21 ����������� ���� ����������������������������������������������� �������������������!����"�������#� ����$�������%��������� &����&''(((�����������'����'���)�� ������

Tables *������!����(���!��������������������&��

Standard settings • %������������(����C��P������������C� P�������������C��P�������������������C�����

• M���������������� �������4+R��!��������(�����(������(�����!������ ������������������������������!�����S���������2�����������(������(������!������������ ���������2�� ���������2�������(�����������������!������ ����6��������������!����(���

• �� �����������&�$�!�)��������

• ��:�����������(������� ��������&�o 6���������������������������<valign=top>�������<tbody>������o 6������.������������������<td>����������&��������o 6������.������������������<th>����������#����(<align="left">>��

• ":�����&�

<heading refname="table1" type="table"><b>Table 1. Table with 3 columns, 3 rows to adapt by adding or deleting columns or rows</b></heading>

<table border="0" cellpadding="0" cellspacing="0" class="data-table-1" width="85%"

summary="Table using a heading tag for the caption, all columns left-aligned">

<tr align="left" valign="top">

<th scope="col">Header 1</th>

<th scope="col">Header 2</th>

<th scope="col">Header 3</th>

</tr>

<tr align="left" valign="top">

<td class="tb-row" scope="row">First cell in first row</td>

<td>Second cell in first row</td>

<td>Third cell in first row</td>

</tr>

<tr align="left" valign="top">

<td class="tb-row" scope="row">First cell in second row</td>

<td>Second cell in second row</td>

<td>Third cell in second row</td>

</tr>

<tr align="left" valign="top">

<td class="tb-row" scope="row">First cell in third row</td>

<td>Second cell in third row</td>

<td>Third cell in third row</td>

Page 10: Formatting and Writing Tips for Method Authors

Formatting and Writing Tips

IBM Rational Method Composer version Page 10 of 21 ����������� ���� ����������������������������������������������� �������������������!����"�������#� ����$�������%��������� &����&''(((�����������'����'���)�� ������

</tr>

</table>

<br />

Special settings • 6���?������ ��������@����������!����������������������� �������������������@���������!����� ����������<<TH>>����������� �����

• �� ���������������������������������������!������:������!�������<��������������������� ���>������������� ���������!������������(�������������(���������� ������(��������������.����!�����������������,����:�����&�Border width = 0��

• ,����� �������������(���� �� ���2�<�����(�������������>����������� ���2��������������<&nbsp;) ���2�������!�������������������

���������� ����������!��������!��������������������������������������� ��������������������������� ���!�����������������������1��$��������������������������������1��$��� ��!����-�"����

Illustrations (graphics) 8����������������������������������<����������>���������2������!����������������!����(����������������!����(���������������������������1��$�!�����

File formats • ����M�,�����E#M�!�������(����������������������������

o M�,����������(��2� ������!������(������������������������o E#M��(��2� ������!������������������������o S�����������E#M��!��������� �������M�,��!����������

• 7���������� ������<��#>�!�����!������������������������������������������

File names and storage • 6������������������������!�������������������� ����!��������������1��$���������2���

• H����������!���������������������������������������������1��$�!��������������������(���������

• 9����������!������.���������������:�����(����!��������������������<� ���:������ ����+�������(���>��8�������������������������������

• #����������������������������������!������������������!�����������2�������������������������������������!����������������������������������������T����������!�������(���������������� ���(����1��$�!����������!��������������������������

Display considerations • ?�����������������<!��������� �����������������>������ ����� ������!����������������������������������@���������������(������ ��������������������������������������������,����:�����&��

�������$$'��������������������������������

Page 11: Formatting and Writing Tips for Method Authors

Formatting and Writing Tips

IBM Rational Method Composer version Page 11 of 21 ����������� ���� ����������������������������������������������� �������������������!����"�������#� ����$�������%��������� &����&''(((�����������'����'���)�� ������

?��������,���������������������!�����!���������� ��������������

• ?�������������������������� ���!�?$����:��������������� ���(�������������(���������������������������������������������� ���������������������������������2��(��(������������������������������������������������6���?������ ��������@�����������

• ?�����������!������!����������:���7������������������� ��������������:�� �:����

• 7����������!����� ���������������G����������*�����!����������������������

• 7��������������!�������(�������������� ������������� ������������ ������������������������������������������*��� �����������������������(����������

• 7�������������������� ���������������������2�������������������� �������������

• 8������������ ������2������������������������!��������������������(�(��������������������������@�������������������������(����������������:�������2�������������

• *���(��)��*�������2��(����������(�������2�(����� ��������

Accessibility requirements �����(��������*������6�������������������������������8� �������������� ��������� �����������(������� ������������������������������������6����������������������!�(���������������������������2������������������������������@���������&��

• "�������������@�����������������������:��<?$�>�������������������������������������&�<img src=”images/filename.gif” ALT=”Brief description of what the image shows”>

• 7����������������������<�����>�������������!����������������������������2��(���������������(���� �����������������������!�(�����������������������!������S������������������!�����������������:���������

• �� ����������1����&��<table> <tr> <th>Column heading name goes here</th>

*������������ ����<����������span�������!������ �������������rowspan�����colspan>���

• 7�����������������������������������:��� ������������ �������������������������������������������

<;�������>�S�����������8� 9������E?86����������!�(����������������������������������������� �����

�����������8� ���������������� �������������������!����������!����������!����������

Globalization considerations ���(���������� ����������������������������������*������������������!���(���������������

Table 2. Words to avoid and what to use instead to ensure accurate translation

Ambiguous Clear

����� ���������

Page 12: Formatting and Writing Tips for Method Authors

Formatting and Writing Tips

IBM Rational Method Composer version Page 12 of 21 ����������� ���� ����������������������������������������������� �������������������!����"�������#� ����$�������%��������� &����&''(((�����������'����'���)�� ������

Ambiguous Clear

������������ ���������������!���

����������!��� �����������!������������

������ �����������

������� �!�����(�����

����������������� �(����������������������

������I���������!�����������!�����J� ���������

������� !���������

���� �����

(���� �������(������

6�����&������� ������������� ����� ������������554�������������������?�������������������

Trademark and copyright rules *���������������������������������� �����������!�����������������G�������.��������������2��?��������������������������������������������������������������!������������������������������������������:��������� ������������������������2��������������������(���������!�����������.�����������������������!�!��@�������������������

Product names 7������� ����������������������������������������� �������������������������������������������2�������������������������"����(���������<����������!�(������>������������������!��������������(�����������-��������!�����<��������(�������������������2���� ����������������>�������������������� �!����-���������������������������������!���������������������������������(���������������:��������!��������������U���O����������������+���������?�(��������������������(����������@����������������2���� �������������� ��@������������":������&�

���������������=�-��������*��!����#������=�<-*#=>������������-*#����������������=�-�������=���������������������������-�����������������������&�����������-���

���������������=�-�������=����������=����������������������

Page 13: Formatting and Writing Tips for Method Authors

Formatting and Writing Tips

IBM Rational Method Composer version Page 13 of 21 ����������� ���� ����������������������������������������������� �������������������!����"�������#� ����$�������%��������� &����&''(((�����������'����'���)�� ������

*��������������2���� ���������������!���������������������:���!����!������������2������������������������������������8� ������S���������������������������������������H������������� ���������������������!������������������������������ ���������������������������������2���������-*#��"�������������������������!������������!��������&�

��������������=�-��������*��!����#������=�<-*#=>������������-*#�

�$������7����������-���!���-�������������������������#���������������(������@�����A-�������A����������� ��@���������� ���!���������!���������������������!�������(����������������������#�������������������G�������������������������������(���� ��!����(��� ��������<��������������������(2(������������>��,����������<�!����!��������>&���

-��������?�����������7�������������!����� #��G����":��������������������������������������������������������2���� ����������������������������2���� ���!���������������������������������������������������������:�����#�����������������������������2���������������:�����!���E��������������������������������������������(������������������������2���������(�����������������������������2���� ���=����!�������!��������H�����(����������������������2��������������������)��(���������2���� ���F�� ���������!����������������������������������������������2���!����������������$�������������������������������G�������������!������������������!�������������������������������������(��������":������&��

���=�-�������=����������=���!�(��������=�-�������=����������=�����������������=�-�������=����������=���!�(��������������������=�-�������=����������=����!�������������������������

�7������������������2������������������

��������������?�����Q��!�������������������������?������������Q��!�������������

7��������������������2�(���(�����������������������������������������*��������2#������������!������������!������������������*��������� ��2�����������

�?������!����(��������(�������������Q������������������������&���������������������������������������2�������������(������P�����!�����(��������������2������������!�������(��������������������������������������������������8� ��������������������������������������< �������������2����6�������?���� ����������������!����������������������������2�����!���(���(����������������������������>&��

• ?�� �=�����?�� �=�#���6�����=��

Page 14: Formatting and Writing Tips for Method Authors

Formatting and Writing Tips

IBM Rational Method Composer version Page 14 of 21 ����������� ���� ����������������������������������������������� �������������������!����"�������#� ����$�������%��������� &����&''(((�����������'����'���)�� ������

• �����=��• �����!������������$� ����=�<���$=>��• ���$=��• $���:=��• �������!�=��• 6���=����������� ����"����=��• 6���������������=�<E���=>��• *H�V=�

�,����(����������������(������������������� ����������������)������������2�&��

• 6�����������������.����������2���:��������������������2��(����������• #����������!�����������������!����)������������2��(������������!������������2��(���&�������������!��������������#�(��#��������������������!���������������������!�=�#�(��#����=�����

Writing tips -�������������������!������ ��������(�������(�����������!�����!�(�����������������������������

����,������������*���������������������������������� ����������������������������

Use active rather than passive voice �

• 8����������������������������������������������� ���������������������������������������������������������������������������������2��������(�����������������

o �������������������(�������� G�����!���������������(�����(�������������2���������������

o ���������������������������������(��������������Q�� ��������������� ������������ G������

o ?��������������������������(������A(�����(����������WA� ��������������������������������������Q�����������������

o ;���������������(�����������������������2������������������(�������2������������(2(����������������������������������� ����������������������������������������������������������(������

o �� ���/���(���:��������!��(������(��������������������

Table 3. Comparison of passive and active voice

(���)��)����� -���)��)�����

,������������(����������������������������� ��������

*�������������������!������������(�������

;��������!���������(����������:������� �����:��������(�����������!�����

?���!��������!���������������������!������������ ��������������������@�������������

S����������������������!��������!���������������������!���������������@�������������

Page 15: Formatting and Writing Tips for Method Authors

Formatting and Writing Tips

IBM Rational Method Composer version Page 15 of 21 ����������� ���� ����������������������������������������������� �������������������!����"�������#� ����$�������%��������� &����&''(((�����������'����'���)�� ������

������ �������������6���������� �������(���!����������������������������

������ ����������������6����������(������������������!�����������������

Write in the present tense #��������������������������(������������������������������������������������������2����������������(������������!����� ����6���������������������������������������������������(�������������������(����������������������������!������:������������(��������������������!�������������������������������������������������������&�U8�������������������������(������������2���������@����������������������O��������������������������(������!��������&�U��������������������2�����������������2��������@���������������������O�

?��������������&�S������������� ���(���������.������(��������������(�����������������������(����������������������������������������.������(������������������(�����������(������� �������������� ����������������������(�����������(�������(2(����������

Learn the most commonly misused words and phrases ��������!��������������6������� ���0���������!����������(���������������������

Table 4. Commonly misused words and phrases

.��������� ����

������������� ��������������C����������������������� ��������<����������>�

�������������� ��������������C��!!���������:����������������

���������� ���������������<!�������� ������A�����A>��

���2���(��� ��������������������

��������� �������� �����������������������������������������:���

�������� ����

�������� (�����

!��������� �:������������ ������������� ��������������������:���

$������ ����������&������������������ !����:���������������������������������!�����

����� ����������

������� �������<���������������!�����������!������!�����������������������>�

������� ������������������������������������������������������������������������:��<���������� ���� ����������������������������������������������������������������������>�

����<��������������(��>� �����������������������<����(��>��

��(���� ��(�����

���������������)������ ������������(�����������(������ �����������G�����������������<���)����������>�

�����.��������.������������ �����

������������� ������������:�����������������(���������������������< ���������!�����������������������>��

Page 16: Formatting and Writing Tips for Method Authors

Formatting and Writing Tips

IBM Rational Method Composer version Page 16 of 21 ����������� ���� ����������������������������������������������� �������������������!����"�������#� ����$�������%��������� &����&''(((�����������'����'���)�� ������

.��������� ����

����� ��������� ���������!��

(� ������(� )������(� ������� 8� �������

(���<�����������������>� (���������������������������������������(�����������������@������������������������� �����������

(���� ������<����(������������������!�����������������������>�

(��� (����

����!���������<������ ��������!�����������>�

�����(��������������������������������������������X���������������2��������������������������������������������P������������������2��������������

�������!!������

���������

�����(��������������������������������������������X���������������2��������������������������������������������P������������������2���������������������!!������

(����� ����������������������������:���������<���������������*6�"����>�

���1��$������!��������������� A���A�

���1��$������!�����������<��Q�Q������������>�

<�>�

Page 17: Formatting and Writing Tips for Method Authors

Formatting and Writing Tips

IBM Rational Method Composer version Page 17 of 21 ����������� ���� ����������������������������������������������� �������������������!����"�������#� ����$�������%��������� &����&''(((�����������'����'���)�� ������

Know which verbs to use or avoid �� ����+��������������� ������������������������(�������(���������(��������:����

Table 5. Verbs to use

Use When referring to or in connection with ������� ���� ������� ��������!���������������������� �������������(�������� ���

��(���� �������< �������������>��

��(���������������

��(����������<���� ��������������>P� ��������������������<����>�

������� �������������2�!���������2� �:�

����2��������������������������)��(��������������!������� ������<����������;9� �����>�������� ������������ ������������ �:��

����������������� G������������ ��������<$�����A7��A�������������P�����!����������������A������������A��������� �� ���A���)���)����A����������� �����������G�������>�

����� �������������������(��2��������������

������� �������������������������

�:������ ����������������P���!�������

!���� �����2�

!������� !������������������2��

������������� (���������������������<���������������!����������������>�

���2���������������!�(�����������

��2�������� ���

�� �����������������������<7����������� ���������������������!�����������������������������������������!�����2������������������� ����,����:�����&����H�:�� ������ ������������� ���������!������������������������������������������!����>��

������ �����������������

����������� ��(���

������������������������������ ����������������

�������(�.����������� �:�����(����(�< ���������G���� ���������� ��������:����������������������������� ������))��������(�.����������>�

������� !���������������������(����2�� �����2���

@���� ���������

�������� ���2� �:��������)��(��������������������������<����������!�������>�

������(�� ��������:���

������������ ���������������������

����� ���(���������������

����������������

���������

������ �������������������� ���������������������������������������!����<M*�>�

����������� ���������

��� 3�������������������6�����&�����"����������������

Page 18: Formatting and Writing Tips for Method Authors

Formatting and Writing Tips

IBM Rational Method Composer version Page 18 of 21 ����������� ���� ����������������������������������������������� �������������������!����"�������#� ����$�������%��������� &����&''(((�����������'����'���)�� ������

Table 6. Verbs to avoid (Note: For legal reasons, IBM does not "recommend.")

Avoid Use instead

� ����� ��������������

����(�*���� ����������(�������������������������(������������������(�������������<!����:�������AS�����������A�I���J�A��������������(�������������A>��

��������� ����������������

�������� ������������

������������<(��� ���������� ���(���������������!�(���������(�������������G����>�

��������������� *��������������������� ���<���������������������>�

����� !��������2���������������������������

���������� ����������

��������� ������

��������(��� (�����

��������<(����(���������� �:>��

������

���<������>� ����������!����(��������!����

����� !�������<���������������� ������2�������� �����>�

�������������� ���������������

��� ������2�������� ���))� ��� �����������(�������������������������(������������������<!����:�������AS��������������������������A�I�������J�A������������� ����������������������������A>�

�:������� �������������������������������

���� ������

����2�� ������������

������� ������������

��������<!����:�������A�������������� �������A�I���J�A������������������������� �������A>�

����!!��!� ����!!�!����

���������<��������>��

�����<��������>�

��(������<����!!>� ��������<����!!>�

���������<�����)�����>�

������

��������� ������

���������� ����������

(��� (����

��� 3/����������������'�6�����&�����"�������������'��

Page 19: Formatting and Writing Tips for Method Authors

Formatting and Writing Tips

IBM Rational Method Composer version Page 19 of 21 ����������� ���� ����������������������������������������������� �������������������!����"�������#� ����$�������%��������� &����&''(((�����������'����'���)�� ������

Proofread early and often • ������������������������2�������������&��������������������(��2�����������������������������������������

• ?�(��������������������������(����������������� �!������ ���������!����������������

• ?�����������!���� �������������������:���������������o 7�����!���������!�����������!����(�������������������:�������2�����!�����������2���

o ?!�����������������������������������������������!�������o #��!����������������!����� �!����������������������!��������(���������������

• ����������������������������������!��������N������ �����:������������N������!�������������������������������������������������������������������������������2��������� ������(�������

Cite sources ?��� ��2���G�����������8� ��������������������(���������������������!������������� ������������������!����������������,������������������������������������������&��� ?�����Q��������� �������!���� ��2�������������������������!���������������������@������������2��<���(������2�>�

/� �������!���� ��2����G�������������������!������������������������������������0� #� ���������8� �����������<��������*-$���������>�+� S�����!��� �������������!�����8� �������������������������!����������������

Use caution when you copy and paste text from other sources ������@������������!��������������������:��!���������������������������������������������������:������������������������2�������������� ���������������������������� ����������

Copying from the Web or other HTML sources 8�����������������������:��!�������������������������������:��������������������������������1��$���������������������������������������:���S����������������!��������������!�����������������������������&�

• #����������������:�����������������������;���������:����������!�������!������:���(���� �����������������-�"��

• #����������:�������������������1��$��� �< ��(���������������1��$�������!�������>��• #����������:�������H�������������������������������-�"���• -����������:�������������� �����������������������

?!���������:��������������������������������������������������!��������������������,���!�:������ ������ ��(�����������!����������1��$���:��� ����������������������������(������V1��$��7;�������66����������������������!�=����������":������=���?����������������������������������������2����1��$���������1��$��� ��!����-�"�������������2��������������1��$�����������!����������������������!������������������?�������������!�������������������������1��$��

Page 20: Formatting and Writing Tips for Method Authors

Formatting and Writing Tips

IBM Rational Method Composer version Page 20 of 21 ����������� ���� ����������������������������������������������� �������������������!����"�������#� ����$�������%��������� &����&''(((�����������'����'���)�� ������

Copying text from Microsoft Word 7������������������������������!�����������!�=�8����� �������8��������������������������������������8��������������������������������������������������������&�

• *�������������!��8����1��$����������������������������!���� ������������ ������(���������������!���!������������������������� ���������� �������,�������1��$�������������&����&''�������������2�������2'���'�:�����'��!��������:��

• *�������������!�=�;!!����� �1��$�,�������� ��(�����������������G� �� ����������������������������!�������������������!���������������������������8����������������������������<�������A8� �#����!�������A����8����� />���������������������������������1��$����������1��$����!�����������!�=����������":��������������������������N�����)��:���������<-�">���

• ���?�� �=�7����(�����=����������������0����!�"#�!�������������������������������������������������G� �� �������������!!�������!����������!����������

��������!��8�������������������������!��������������A������@������A�(������������������!�@������������2��������������8�������������������� ���� ���������������������?H6����:�������������8��������:�����������������������������A������A����������������������������������������@���2�!�:�����������������!���������������8���&���� ;��������� �������������������-�����������1���������� ����2����-����������� ����������������.�����2��������3�����2�*����2�����3�����2'�

Other tips -��������������������������Y����������������(���������������2��������������������������������(�������A,����:�����A����A,�����������A�����������������������������Q���������������������������������

":���������2�������������������������!���������������������������������(�������:��������*����������������Q�������� �����������!�����������������!���������������������:�������?������:��������������������Q����������������:��!���������������������������������������$���������������������������������������������:��������":��������������������������������������������������P�G������������������������2������������������������������� ��� �������������������������(������������

����������������������������(����������������&���N�������� ����������������������������������������������������S����������!���������� ����!�������<������� ��A����A�������������������>���

-������������(�����(��������G����������������� ����������������&������������(�����������!���������

H���������A� ���A�����A ���(�A� ��������������������������������������������������������������������(��������������������������!����������&��������������������������������!����(����(���!����(���

6����������������!����&�M�����:�������������������������������������������2�������2������ ��2��!������:�����������������������!���������������������������������

*������������ ���������������������������������

8���������������P��������� ��������

�!���N��� ����������N����������

Page 21: Formatting and Writing Tips for Method Authors

Formatting and Writing Tips

IBM Rational Method Composer version Page 21 of 21 ����������� ���� ����������������������������������������������� �������������������!����"�������#� ����$�������%��������� &����&''(((�����������'����'���)�� ������

7��N������������������*��������(�������� ���������� �������������������������������������

�!�������������������������������!��������� ����������������2������������

-���� ��������������&��

• ?���������������������������������������

• ���������Q��������������� ��������������������(���������������������������� )���(�������

• $��� ���2���!���:������ ����������������������������?������������������2����������������������!��������������������������������2��!���:����

����2������������!����������������������������������2���

-���� �������������:��(���� ��������������������������������?����������(���������������������������������������������������������������������

?�������������������������������(������������������������"������,����:��������������(�����A��������<�>�A������������������������������������������������������������������������A�������������������������� ���A�

?������ �����������������������������(������������������������������������(�������������?����������� ������������!�����������������������!��������������,����:���������!������A����-��������*��!����#�������<-*#>A� �!���������A-*#�A���

Legal notices ����������� ���� ��������������������?���-����-��������������������������6�!�(����M������-������ ��6�������HS�� +45��#��������������*������6�������!�?�������������������������������-���������������������2���!��������������������������������������������������*������6������������������������� ����;������������������������������������������� ����������2�����������������������2����������������2���!��������-�!����������������� �����������������������������������������������������������������������2������������ �����������������������(�����������������?��������������������������!�������������������������������� G���������������(�����(���(������������������������������������� G��������������?$$��H,;-�?��;H��6�#-;%�7"7�;H�?H�U?6)�6O��?6�6��8��1;*��?HS�8?--?H�S�;,�?HS�9�H7������������������������������������ ��!��������� �������