Headings are essential elements of software documentation, as they help readers navigate, scan, and understand your content. But how do you choose the right heading level for your documentation? In this article, you will learn some best practices and tips for using headings effectively and consistently in your documentation.
Headings provide structure, hierarchy, and context to your documentation. They help readers find what they are looking for, follow the logic of your argument, and identify the main points and subtopics of your content. Headings also improve the accessibility, readability, and usability of your documentation, as they allow screen readers, search engines, and other tools to parse and present your content in different formats and devices.
Headings alone do not enable the parsing and presentation of content. If I create a document in a traditional word processor, and manually make my most headings look different depending on their importance, then the user will understand my intent. However, most electronic systems will not. We need to use more powerful tools, such as structured authoring in XML, to really make meaning from our content, which can then be delivered to different platforms for consumption. We need to be very clear in the distinction between presentational headings versus structured documents. Even in common word processers, using heading and paragraph levels (usually linked to styles) is very different to just applying formatting.
Heading levels are essential for indicating the importance and relationship of different sections and subsections of your documentation. Generally, the most common heading levels used are H1, H2, H3, and sometimes H4, depending on the length and complexity of your document. It is important to use heading levels consistently and logically throughout your document. Make sure to use only one H1 heading per document, usually as the title or main heading, and utilize H2 headings to divide your document into major sections or chapters. Additionally, use H3 headings to divide your H2 sections into sub-sections or topics. Use H4 headings sparingly, if needed to further break down your H3 sub-sections into smaller parts or details. Avoid skipping or jumping heading levels as this can confuse readers and break the hierarchy of your document. Moreover, try not to use more than four heading levels as this can make your document too complex and hard to follow. If you need more than four heading levels, consider splitting your document into smaller documents or using other methods such as lists, tables, or diagrams to organize your content.
Again, I feel this is a very limited approach. If I am writing a proposal to a potential customer, I might use a word processer and H1 through H4 for breaking up the different sections of the document. At most, however, this will be delivered as a word processor document or maybe a PDF. In reality, for technical writers and authors, we should be using more powerful tools if we are considering producing documentation that could be delivered to diverse platforms. Do I, as the author, even know how my content will be consumed by the end user? Paper; PDF with some hyperlinks and contents; electronically via phone, table or computer with full interactivity; maybe even in AR or text to speech? My source must be format agnostic to achieve this.
Headings should be clear, concise, descriptive, and consistent in style, tone, and format throughout your document. To write effective heading text, use keywords and phrases that match the expectations and needs of your audience and reflect the purpose and scope of your document. Utilize parallel structure and grammatical form for headings at the same level, such as using nouns for all H2 headings. Choose between sentence case or title case for your headings; whichever you choose, be consistent throughout. When it comes to punctuation, use it sparingly and appropriately; generally avoid using periods, commas, colons or other marks at the end of your headings, unless they are part of a question or quotation. Hyphens or dashes can be used to separate words or phrases in your headings, but don't overuse them.
As a general rule, make sure content within each heading is related. H1s introduce main topics. If these breaks logically into subtopics, then use H2, and within H2 use H3 and so on. If something in one of your subtopics is not related to the parent, it must go in a different parent - never mix topics. In addition, use headings sparingly and only when required to differentiate topics and subtopics. If a heading contains just one child heading, then that really is not required. Finally, once you have started using headings in a section, keep using them for all the relevant breaks in the subject matter. You can't give one topic a heading but then not use a heading for the next topic. Plan your structure first, then fill with your content.
When formatting your heading text, it’s important to create contrast and hierarchy among your headings. You can use larger font sizes for higher-level headings, bold or italic font styles for emphasis, and colors that are consistent with your brand identity. Additionally, you can use horizontal lines, white space, and indentation to separate and align your headings with your content. For example, use 18pt font size for H1, 16pt for H2, 14pt for H3, and 12pt for H4; bold for H1 and H2, italic for H3 and H4; 24px of space above and below your H1 heading, 16px of space above and below your H2 headings, 12px of space above and below your H3 headings, and 8px of space above and below your H4 headings; as well as indenting your H2 headings by 16px, your H3 headings by 32px, and your H4 headings by 48px. These techniques will help you inform and reassure stakeholders while providing valuable insights for improving the document.
As I mentioned previously, and considering that this topic is for 'software documentation' then as authors we really should be beyond the realms of the office word processor for creating our documentation. What if I want to use the same content for printing a user manual, delivering it as a PDF, or maybe embedding pop-up help within the application? While I agree that our heading levels must be distinct and give the reader understanding of the structure for our documentation, to limit ourselves to thinking in terms of format on a page should be consigned to the history books - under the heading of obsolete ways of publishing!
The final step in choosing the right heading level for your documentation is to test and review your headings for clarity, consistency, and accuracy. To do this, you can read your document out loud or use a screen reader to listen to it. You can also create a table of contents or an outline to view the structure and hierarchy of your document. Additionally, you can use a readability or accessibility tool to measure the quality and usability of your document. Finally, you can ask for feedback from peers, stakeholders, or users to see if your headings meet expectations and needs.
Having been involved in documentation review and proof reading for many years, then I agree with these tips. Read out loud - this forces you to understand each word as you say it, rather than in your head 'reading' what you intended or thought you'd written. Also, use peer review. They don't know your thoughts and words and are more likely to question ambiguity - especially if they are *not* an expert in the topic.
Creating your heading structure before writing the content is a far better way of documenting technical information. Your headings will help you identify the points that need writing about, and you can juggle them around to create a logical flow, grouping together the relevant topics and subtopics in a way that the user will hopefully find most useful. This has an added benefit - by creating the headings first, you then only need to fill in the content under each heading. This helps you to keep each section relevant, avoids repetition, stops you writing the same thing more than once, and keeps your writing concise. And to the point. In everything you write, remember you are writing for new users, not the developer or familiar user.