Editorial guidance for writing content that works well with Beacon.
Good Content Drives Good Results
Clear, relevant, content let’s AI understand and use your information accurately. Well-crafted content leads to better results for Beacon.
- Use Headings & Subheadings: Break content into scannable sections
- Organize Logically: Keep related information together in a clear flow
- Keep it Clear & Concise: Easy-to-read language helps everyone, including AI
- Provide Context: Summaries, titles, and AI metadata guide both readers and AI
Quick Assessment: Is Your Content Ready?
Before diving into details, ask yourself these questions:
- If someone asked your most common question, is the answer clearly written on a page?
- Are your page titles and headings descriptive?
- Can each page stand alone?
- Do you know your visitors top 10 quesitons?
If you answered no to any of these, that would be a good place to start before looking at advanced optimization.
Principles for Beacon Friendly Content
Beacon looks for answers. Put them where they can be found.
Headings helps people and machines find the right section. When someone asks a question, Beacon looks for headings that match. “Overview” and “Details” don’t tell anyone what’s in that section.
Less effective:
- Overview
- Details
- More Information
- FAQ
More Effective:
- How to request a YaleSite
- Required Documentation
- Deadlines and Exceptions
- International Travel Rules
Each section of a page should make sense on its own.
Less effective:
“As mentioned above, the deadline is 60 days. See previous section for documentation requirements”
More Effective:
“Submit within 60 days of the expense. You’ll need receipts for purchases over $75 and all lodging receipts regardless of amount.”
Repeat key information rather than referring readers elsewhere.
Don’t assume readers have context. What may be obvious to you might not be obvious to visitors or Beacon. Spell things out.
Less effective:
“Contact the office for more information”
“Use the standard form”
More effective:
“Contact YaleSites at yalesites@yale.edu“
“Use the YaleSites Go-live form”
Be specific by naming the office, linking to the form, or describing the steps.
Outdated answers leads to outdated answers. Regular content reviews are important and help keep your content up to date
If you know the questions visitors are frequently asking your unit, make sure the site addresses it thoroughly
Group information that is related to each other together. Clear structure helps the AI find and retrieve content.
Evaluate your content
Try this content exercise to see if your content exists clearly on the website.
-
Identify your top 10 questions
What do people email you about? What does your front desk answer repeatedly? What would a new visitor need to know first?
-
Make sure each answer exists clearly
For each question, find the page where it’s answered. If the answer is buried or unclear, fix it. If it doesn’t exist, create it.
-
Test and Fix
Ask those 10 questions in Beacon. If the answers aren’t good, improve the content and test again.
Content Considerations
Beacon can read PDFs, but content on web pages is preferred by the AI. PDFs are useful “in a pinch,” but consider:
- Is this content better as a web page?
- Is the PDF text-based (not a scanned image of the data)
- Table’s on pdfs do not work well with Beacon. For tables on PDFs create a table on the YaleSite page using the insert tabe in the text block.
Content Audit Checklist
Use this checklist to review your content
Page level review:
- Page title is specific and descriptive
- Heading describes what’s in the section
- The main answer/point is closer to the top
- Sections make sense on their own
- Contact information is specific (names, emails, “business hours” vs “9am-5pm Monday - Friday”)
Site level Review:
- Top 10 visitor questions are clearly answered somewhere on the site
- No duplicate content with conflicting information
- Navigation helps visitors find key information
- PDF’s are text-searchable, not scanned image or tables
- Ambiguous terms are clarified or consistent
Writing for Beacon vs. Writing for the Web
Writing for the web well and Beacon overlap significantly. Here’s how they compare:
The Same
- Clear, scannable structure
- Plain language over jargon
- Logical organization
- Descriptive headings
- Accessible formatting
Different for Beacon
- Answers in content should be explicit, not implied
- Context can’t rely on page hierarchy
- Headings do double-duty (human scanning and Beacon retrieval)
- Repettion is ok (better than refering content on other pages that lose context)
Ready to Test Your Content
Good content is the foundation. Now learn how to test and maintain your Beacon.