~ubuntu-core-doc/ubuntu-docs/maverick

<chapter id="information-design">

        <title>Information Design</title>

        <sect1 id="audience">

                <title>Define Your Audience</title>

                <para>TODO: Importance of knowing who you are writing for.</para>

        </sect1>

        <sect1 id="scanning">

                <title>Write to Facilitate Scanning</title>

                <para>Users need to find information quickly. People don't read documentation as much as they scan it for solutions to their immediate problem. Writing and presentation styles that seem redundant in essays or other texts are often helpful to people scanning for information.</para>

    <para>Readers can find and absorb information more quickly if documentation is clear, concise, and consistent. As well, translators can more easily translate documents with these attributes.</para>

                <itemizedlist>  

                        <listitem>

        <para><emphasis role="bold">Writing must be clear:</emphasis> Write short, active sentences using everyday vocabulary. Maintain a visual separation between page elements.</para>

                        </listitem>

                        <listitem>

        <para><emphasis role="bold">Writing must be concise:</emphasis> Minimize content so it can be found and remembered. Keep pages short, modular and focused on a single topic.</para>

                        </listitem>

                        <listitem>

        <para><emphasis role="bold">Writing must be consistent:</emphasis> Refer to one thing or idea with the same word throughout the page. Use headlines, lists and emphasis to signal importance.</para>

                        </listitem>

                </itemizedlist>

        </sect1>

        <sect1 id="writing-style">

                <title>Match Writing Style to Purpose</title>

                <para>Use a writing style that fits the text's purpose. The most useful styles in documentation are explanatory, procedural and descriptive.</para>

                <para>Explanatory writing is used for special language or concepts that users need to understand a procedure. Format explanatory text in paragraphs.</para>

                <para>Procedural writing is used for telling readers precisely what steps they must take to complete a task. Write procedural text as numbered lists. Tell users what to expect when they've finished.</para>

                <para>Unlike the other two, descriptive writing is used primarily in reference material. It gives a short definition or identifies where a feature can be found. Lists and tables are useful in formatting descriptive text.</para>

                <para><xref linkend="styleguide-international"/> gives more guidance on writing style.</para>

        </sect1>

        <sect1 id="formatting">

                <title>Match Formatting to Importance</title>

                <para>Formatting text gives a visual hierarchy that lets users see the overall content of the page by scanning it.</para>

                <para>Headlines summarize the topic of the underlying information. Scanning headlines gives the user an accurate picture of the detailed contents.</para>

                <para>Lists allow users to skip over explanations they don't need and get straight to a solution.</para>

                <para>Admonitions (callouts) package relevant information that doesn't fit into the primary flow of the topic.</para>

                <para>Emphasis lets people pick words out of paragraphs, lists and examples; giving them an idea of the topic details before reading.</para>

                <para>Formatting Conventions lists visual styles and their use.</para>

        </sect1>

</chapter>