Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Is there any benefit when writing out instructions to split it up into lots of little paragraphs, or is it better to leave it in one paragraph?

+5
−0

I was putting together an instruction page (for setting up a game that my business created), which included a whole lot of various pointers, most of which were only a sentence or two long. These explained various parts of how the game setup worked.

I noticed while editing this document that the other person working on this document — who had originally written it — had included everything in one large paragraph; each piece of information followed the previous one without a linebreak. This resulted in a medium-sized paragraph, containing about four or five various (albeit related) topics.

I instinctively split this up into a whole bunch of smaller paragraphs without even really thinking about it, since that's just how I write; heck, even here in this question I've just been breaking into a new paragraph every two sentences or so.
After doing this, however, I started wondering if this was actually advantageous. After all, the person who wrote that section originally is much more experienced than I am (by... several decades), so maybe I'm the one who's wrong here.

Is there any benefit when writing out instructions to split it up into lots of little paragraphs, or is it better to leave it in one paragraph?

I'm defining "better" as "more likely to get the point across and prevent misunderstandings".

History
Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

0 comment threads

3 answers

+8
−0

Writing in fuller paragraphs feels like it creates better reading flow, as opposed to short choppy chunks of text, but that's a prose consideration. For instructions, the primary goal is to help the reader do all the necessary steps in applicable order. If lots of steps are combined in a single paragraph, there is greater risk of the reader missing a part.

In many style guides, procedures are even spelled out as numbered lists. The reader can then track progress through the list more easily. This can be overkill if there are only a couple steps but important if there are many, so use your judgement.

Whether you present it as paragraphs or list items, keep it to one logical chunk of work per chunk of text. A chunk of work might combine several elements -- "fill out your shipping and credit-card information in the form", for example, as opposed to spelling out the individual steps. Think about the logical chunks from the user's point of view, including how the UI guides the user.

For non-technical examples, consider recipes. You've probably seen a bunch. Which style is easier to follow when you're actually cooking, as opposed to when you're browsing cookbooks trying to decide what sounds good for dinner?

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

+3
−0

As already said, instructions are about helping the reader do the steps in the right order without missing any of them.

This, of course, can take different forms in different contexts.

Recipes is one example. Another that I am personally familiar with is airplane checklists, which have the pilot take a series of steps, usually manipulating or verifying controls or instruments, in a specific, proper sequence which has been developed to get proper results for what one is trying to do. Pilots are trained right from early basic training to follow checklists precisely because doing so reduces the risk of an error or omission.

Typically, this takes the form of some variation of "challenge - response" or "control or instrument - state"; such as "navigation lights - on", "flight controls - free and correct", "vacuum suction - green range" or even "propeller area - clear". For an example of what one might look like, here is one for a typical trainer (a Cessna 172S), and here is a partial checklist for a Boeing 737-700/800.

As you can tell, this is hardly proper English prose. It is, however, clear, specific and focuses on a single item at a time. With one item done, the pilot moves on to the next item on the checklist.

One specific airplane I've flown as a pilot has a pre-flight checklist that lumps together several items into one.

The result? Unless I am paying very close attention, it's very easy to miss a step that's buried in the middle of what's basically a block of compactly written text -- which more or less obviates the entire purpose of having the checklist in the first place, because the reason why one has the checklist at all is to ensure that none of the steps are missed.

Now, airplane checklists are a bit of an extreme case in no small part because of the potential consequences if a step is missed (really, airliners have crashed because a single control has been in the wrong position), but they have got to where they are over almost a century in part precisely because the format ensures that if only they are executed from top to bottom without jumping around, nothing is missed.

Therefore, if you want to make certain that nothing is missed, I would say to clearly delineate each step. If you want the prose to read more fluidly, and are willing to accept the fact that the reader will need to parse each part out of the text and especially if they are in a stressful situation or if a step takes a long time to perform might miss something, then by all means you can put multiple items in the same paragraph.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

+2
−0

In addition to what has been said about the ability to follow steps, the same thing would apply to a bunch of individual tips that don't have to be followed in order: Make each one a separate paragraph. In fact, it is even more important for tips than for steps, since readers know they are supposed to do all the steps of a procedure. But they will miss tips altogether if they are buried in a single paragraph.

The reason for this is simple. People skim through a text looking either for the information they need or something that might interest them. They read the first few words of a paragraph and, unless it looks interesting or relevant, move on to the next paragraph. If the first sentence of a paragraph does not signal what is in the paragraph, it is unlikely that most reader will find that information.

If you put a bunch of tips in one paragraph, the reader will read the first tip. If it interests them, they may read on, assuming that the rest of the paragraph expands on the first tip. But if the first tip does not interest them, the won't read the rest of the paragraph and thus will not see the rest of the tips.

Not only should you use separate paragraphs, you should make them into a bulleted list. For reasons that are not entirely clear, people love lists. (Look at how much click bait is made up of lists!) Formatting something as a list automatically draws the reader's eye.

Adding "Best" or "Worst" to the title similarly adds interest. Title your tips something along the lines of "Our Experts Ten Best Tips" and readers will really pay attention to it.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

Sign up to answer this question »