This post provides some hints and tips for writing posts! 🙂 … things to consider when writing a blog or resources (docs) page

If you want authoring help with something not mentioned here, please add a comment to this page.

July 2017: This site now uses the IBM Northstar design

From July 2017, this site uses the IBM Northstar design and some older techniques no longer work. You can use IBM Northstar techniques; for example for grid layout and to show/hide content. For more information about and examples of IBM Northstar techniques, see IBM Northstar Design and code.

Just write, or add HTML or WordPress tags

To add content to a new post, use the Text editor mode; not the Visual editor mode if it is available to you. The Visual editor mode can do bad things to your content, particularly when you switch back and forth between Visual and Text.

In the Text editor mode, you can add content to a new post by just adding text without using formatting tags, separating paragraphs simply by blank lines. However, if you want more than basic presentation you can add HTML tags. Similarly, if you want to provide a responsive design for different devices, usually to handle multiple columns on mobile devices with restricted display area, you can add WordPress tags.

For standard content structures like lists, code, or block quotes, use the formatting options at the top of the Text editor pane, or add appropriate HTML tags. This helps to ensure a good, consistent standard of content presentation.

Example tips for lists:

  • Click a list type icon to start the list, add all the list items, and then click the list type icon again to close the list.
  • To add a list item, you can select the content and then click the li icon
  • Adding HTML tags

    You can add HTML tags by typing them, by clicking a tool at the top of the Text editor pane, or by copying HTML source from somewhere else and then pasting into the Text editor pane (for example: view another blog; highlight the content that you want to use; copy the selection source; paste the selection into the Text editor pane, which will preserve the HTML tagging in the selection).

    If you want to add HTML to embed an image, or an HTML link to some other file hosted in this community site, you can use the Add Media button.

    In this site, you can use some special combinations of HTML and CSS to try to provide better presentation of content, as described in the section Some special HTML+CSS use (Work in progress).

  • Adding Northstar tags for responsive design

    If you want to provide a responsive design for different devices, usually to handle multiple columns on mobile devices with restricted display area, you can add Northstar tags for grids that allow the columns to flow automatically to suit different devices. For example:

    <div class="ibm-columns" data-items=".ibm-card" data-widget="setsameheight">
        <div class="ibm-col-6-2">
    This appears in the left 1/3rd of the page.
        </div>
        <div class="ibm-col-6-4">
    This appears in the right 2/3rds of the page.
        </div>
    </div>
    

    In this example,

    • “ibm-columns” defines a row of columns. Each row is divided into 6 units of the horizontal area that can be combined into one or more visible columns.
    • “ibm-col-6-2” defines the left column that forms 2/6 of the total horizontal area
    • “ibm-col-6-4” defines the right column that forms 4/6 of the total horizontal area


    You can use different combinations of “ibm-col-a-b” to present 1, 2, 3, or perhaps more columns that can flow automatically.

  • Adding WordPress shortcodes for tabbed layout

    If you want to separate content onto different tabs, you can use the WordPress tabs shortcodes; for example:

    [tabs]
    [tab text="Label for tab 1"]
    ... the content to appear on tab 1, which is opened by default.
    
    [/tab]
    [tab text="Label for tab 2"]
    ... the content to appear on tab 2, which is opened if the user clicks on the tab label.
    
    [/tab]
    [/tabs]
    

    These tabs appear as follows:

    … the content to appear on tab 1, which is opened by default.

Test the content for presentation and accuracy

Use the Preview button to test the presentation of your draft post.

You can let others review your draft post by selecting the Enable public preview checkbox, and then sharing the URL provided. Note that the URL lasts for 48 hours, and a new URL is provided for you to share after each 48 hours.

Test your post for accuracy against whatever you are describing. For example, if you are describing a feature or use of a user interface like IBM App Connect on IBM Cloud, test that the labels in your post match those displayed on the user interface, that screen capture images match the user interface, and that steps taken to achieve something are described properly.

If you have a lot of content, consider using collapsed sections for the detail

This isn’t the first thing that an author normally thinks of, but it explains what has been done in this post!

A long blog post or Docs page can seem overwhelming so, if you have a lot of content, consider using collapsed sections for the detail, with each section preceded by only an overview. Users can then easily scan the overviews and then expand the detail for sections that they are interested in.

Otherwise, instead of one lengthy post, consider a series of posts (if that is appropriate for your subject).

An example using a collapsed section:

This example shows the use of a collapsed section preceded by this overview and title. Click the “Details” label of the collapsed section to display the details.

  • Details

    If you want to add a collapsed section, use a Northstar show/hide technique; for example, this item uses the “twisty” technique that is convenient for basic show/hide items (For more significant items, I use the “basic show/hide” technique):

    <ul data-widget="twisty" class="ibm-twisty">
        <li>
            <span class="ibm-twisty-head"><strong>Details</strong></span>
            <div class="ibm-twisty-body">
    ... content to be shown when the "Details" head is clicked.
        </li>
    </ul>
    

    And more content after the collapsed section.

IBM Northstar page: https://www.ibm.com/standards/web/components/show-hide/

Add an excerpt, as a short description to be shown under the post link in lists, like the Blogs list or Docs category list

In the Blogs list or Docs category list, the link for each post should be displayed with an excerpt underneath to help users decide whether to open the post. For example:
postexcerpt

  • How to add an excerpt

    When editing a post, choose one of two alternative techniques to add an excerpt:

    1. If the first one or two sentences of your post is good for an excerpt, add the following WordPress tag after what you want to use as your excerpt:
      <!--more-->
      

      The content before the <!--more--> tag is used as the excerpt for the post, and is included in the post content along with content after that tag. For example:

      Two videos have been posted on YouTube that give a snappy 10 minute introduction to DFDL for newbies, <a href="https://www.youtube.com/watch?v=G2iVcJxjdnQ&feature=youtu.be" target="_blank">'An Introduction to DFDL'</a> and <a href="https://www.youtube.com/watch?v=FDBYJXC3Vpg&feature=youtu.be" target="_blank">'First Steps with DFDL'</a>.<!--more--> They complement the longer DFDL videos ...
      

      To add the <!–more–> tag, you can click where you want to add it, and then click the more button at the top of the Text editor pane.

      Note:
      The excerpt can include HTML elements, like the HTML links in the preceding example, but the WordPress tag, <!–more–>, should not be within any HTML element.

      For more information about the WordPress tag, see https://en.support.wordpress.com/more-tag/view-all/.

    2. If the first one or two sentences of your post is NOT good for an excerpt, add a short description in the Excerpt field just after the WordPress SEO section; for example:
      postexcerptfield

      The Excerpt text appears only as the excerpt with links to the post. It does not appear within the post.

      Note:
      If you cannot see the Excerpt field, select the Excerpt checkbox in the Screen Options at the top of the editing window.

      The excerpt can include HTML elements, like the HTML links in the example for the <!–more–> technique.

Add SEO metadata to improve presence in search results (by Google etc)

To improve the presence of a post in web searches by Google etc, you should add metadata to the SEO section when editing your post. You can also use the Editing tools to check the SEO status.

  • Details

    A general aim is to make sure that the “focus keyword” appears in the following aspects of your post. (The “focus keyword” is a few words that someone might typically search for to find your post.):

    • Heading. When you create a new post, include the focus keyword in the Heading.title field.
    • Title
    • URL. When you save a new post, the Heading is used for the post URL; for example “IBM Integration Bus JDBC Connection Pooling” becomes ibm-integration-bus-jdbc-connection-pooling in the URL.
    • Content
    • Meta description

    For example:

    • The Heading/title adds to the URL by default, and the author has used the focus keyword in the content:
      postseo2
    • The author has completed the WordPress SEO section, and the checks show green:
      postseo

Add a few tags

Users can click tags to display groups of posts classified for the subject of the tag.

Consider adding some existing tags for subjects like specific technologies and IBM Integration products.

If you need to, you can add a new tag for a subject that has not been defined already but is a subject that users are particularly interested in. If you are thinking of adding a new tag, please contact Ian Larner to help maintain the tagging strategy for the site.

Remember that users can search the site for subjects, so you should not add tags for every subject that your post might cover.

Try to add only a few tags, perhaps no more than five. It is much better to add only a few tags than to overload the post and site with too many tag choices. The site already has an overwhelming tag cloud, which we are trying to simplify.

Some don’ts

Generally don’t add CSS styles to get a specific effect; we should all try to use Northstar CSS classes for standard effects … except in some cases where those classes are not needed(!). If you think an effect is odd, or think a new effect is needed, add a comment to this blog post.

  • Do not add CSS styles to <code> elements. The presentation, including font size, is determined automatically by the common CSS to be similar in font size to other text with a grey background; eg. Here’s some code in a default code element.
  • For ordered sub-lists (HTML ol), do not add the Northstar classes ibm-alpha-list or ibm-alpha-roman. The type of list is determined automatically by the HTML nesting level, to give list level labeling of integer, alpha, and roman; eg with default HTML ordered list tags:
    1. A first-level list item.
      1. A second-level, alpha, list item.
        1. A third-level, roman, list item.
      2. A second-level, alpha, list item.
    2. A first-level list item.

Some special HTML+CSS use

In this site, you can use some special combinations of HTML and CSS to try to provide better presentation of content, as follows… (Work in progress)

Note box with drop shadow

To present a note type as a more-prominent box, with grey background and drop shadow.
Use a div, <div class="pn-notebox">...</div>; for example:

<div class="pn-notebox">
<p><strong>Note:</strong> ... this is the content of the note box ...</p>
</div>

Which is presented as:

Note: … this is the content of the note box …

Paragraph that introduces a list

To present an introductory description before a list, with minimal white space between the introduction and the top of the list.
Use <p class="listintro"> for an introductory description before a list; for example:

<p class="listintro">Some words to introduce the following list:</p>
<ul>
	<li>List item 1...</li>

	<li>List item 2...</li>
</ul>

Which is presented as:

Some words to introduce the following list:

  • List item 1…
  • List item 2…

For images with “full size” link, add a hint after the image

If you include an image at a reduced size, but wrapped with a link to view the image at full size (as by the WordPress Add media option “Link to: Media file”), add a hint after the image by using the following HTML: <em class="clickimage">(Click image to view full size)</em>

For example, see images in the tutorial Syncing Salesforce leads with an on-premises sales system.

1 comment on"Hints and Tips for writing posts"

  1. Excellent post for technical blog writers…!!!

Join The Discussion

Your email address will not be published. Required fields are marked *