Text guides

Content publishing

Turn your knowledge and source material into useful pages. Keep claims traceable, give readers a clear answer and make the next edit obvious.

12 practical tasks. Each guide includes a sample request and a way to check the answer.

Build an article brief around a reader's questionStart with one question a specific reader would ask, then write the answer in a sentence or two. List the evidence and examples that answer needs, and state what the article will leave out. A section that does not serve the answer can be cut before it is written.
Check the claims in an article draftList every statement of fact in the draft, find the source for each and note what that source says. Cut, soften or research any claim without support. Record the date you checked, since sources change.
Decide which old pages need a real updateAn old page needs an update when its facts, steps or links no longer work for the reader, or when it misses what readers now ask. Review each page against its purpose, note the specific problem and write the correction. Leave pages that still work alone.
Correct a mistake in a published newsletterA good correction says what the newsletter got wrong, gives the right information and tells readers whether they need to act. Keep it short, put the correct fact first and cite the source. Do not repeat the wrong statement in a way that reads as true.
Outline an article from an expert interviewSort the interview into the questions a reader would ask, then place each speaker point under the question it answers. Note where in the transcript each quote sits. Keep the speaker's hedges and limits, and list every fact that still needs checking elsewhere.
Choose examples that explain an article's main pointAn example earns its place when the reader can see an input, follow the reasoning and reach the result. Pick the concept readers find hardest, then choose or build a small case that shows it. Say when an example is invented, and state where it stops applying.
Inventory website pages before a content cleanupBuild a table with one row per public URL. Record why the page exists, who it serves, who maintains it and what should happen next. Decide on merges or removals only once the full list is in front of you.
Make a web page easier to read and navigateStart with the page's heading outline, then fix vague links and hard passages one at a time. Keep every fact, date and requirement as written. Each edit should make the page clearer without adding or removing information.
Draft alt text based on an image's purposeDecide what an image contributes to its page before drafting alt text. A photograph may convey information, identify a link or serve as decoration. Describe the information or function a reader needs. For a purely decorative HTML image, specify an empty alt attribute: alt="".
Write a newsletter subject line the issue supportsName the most useful item in the issue in the words a reader would use for it. Then confirm that a section of the newsletter delivers exactly what the line promises. If you cannot point to the section, change the line.
Add useful navigation to a long guideList the tasks readers arrive with, then link each to the heading that answers it. Label every link by the content it leads to. Where a reader task has no matching section, record the gap instead of forcing a link.
Make a publication checklist for one articleGo through the article and list every claim, then record its support. Check permissions, label each example as hypothetical or real, and open every link. Name one person who gives final approval so the checks have an owner.

Related topics