Writing structured content

At Skylight, we write two kinds of content: structured and unstructured. Most of our technical and public-facing documents are structured, following standardized content templates. These templates make both writing and reading easier. They also help future-proof our documents, making the work reusable outside of where it was originally published.

This section highlights a few common types of structured content that we write at Skylight.

Blog posts

The Skylight blog is a place where we share what we’ve learned, what we’ve made, and what we do in an accessible, public way. We work in the open and share information that makes our work understandable and usable. We write frankly about the challenges we encounter and detail the lessons we learn when making tough decisions. For an example, see A human-centered approach to rebuilding the U.S. Refugee Admission Program.

In sum, our goals are:

• To share our work with the public and detail the lessons we’ve learned
• To strengthen our relationship with customers, partners, employees, and prospective hires
• To actively promote innovation in government digital services, wherever it’s happening

Keep it user centered

Blog posts should offer something to the reader, whether that’s a new tool for them to use, a guide they can use to improve their own work, or educational information about a complicated topic or process. You should begin with the thing your readers should take away from your post, and why it matters to them.

Keep it human

Blog posts are written by people, for people. Don’t be afraid to put yourself into your writing, either as a character or through some of your personal style. Share the story that shows the reader why you’re so passionate about a subject that you took the time to write about it.

If it feels like a marathon, make it a series

No single post is going to cover the breadth of a topic or completely convince an agency to adopt our practices. The goal of a blog post should be to communicate one idea clearly, and make it short and readable enough for your audience to read the whole thing. It’s likely that as you’re writing a post, all kinds of details and new ideas will pop into your head. Consider breaking up your post into a series that will bring the reader along to learn a new skill or gain a deep understanding of how a product was built.

Template

Use the Blog Post Template Locked to help you craft your blog post.

Authorship

The authors listed on a blog post should be only the people who have actively contributed significant portions of text to the blog post. Generally, posts should only be written by one or two people. Limiting the number of people who write a post makes it feel more personal and less written by committee, allows for a stronger voice in the writing, and helps speed up the editing and approval process.

Case studies

Case studies take a high-level look at a complete Skylight project. They’re generally more structured than blog posts. Case studies should convey big-picture details about a project, such as who the users are, what their problems are, and how Skylight helped solve their problems. At the end of the day, case studies are tools for demonstrating the value that we can provide to prospective clients and teaming partners. Therefore, we’re aiming for compelling, “executive-level” narratives. For an example, see Modernizing COVID-19 testing and reporting in non-traditional healthcare settings.

Template

Use the Case Study Template Locked to help you refine your case study narrative.

Employee spotlight post

As Skylight grows, it’s important for us to continue to recruit amazing people. It’s also important to us that we further your career by giving you opportunities to build your personal brand.

An Employee Spotlight Blog Post is a great way to achieve both. By showing people a bit about who we are, what we do, and why we do it, we make what could seem wonky a bit more relatable. For an example, see Gianna Buda: Launching a civic tech career.

Template

Use the Employee Spotlight Blog Post Template Locked for drafting purposes.

Style guides

We often develop project-specific style guides to support our partners and their audiences.

Guidelines

Here are a few things to keep in mind when you’re developing style guides:

Respect the partner’s existing style. Assume that your partner has a style guide and ask about it.

• If they don’t have a style guide, start with AP since we’re most familiar with it and many of our partners use it.
• If any of the existing style guidelines inhibit clarity or usability, talk with the partner about it, backing up your recommendations with insights from user research.

Keep it brief. Don’t try to document every possible grammatical or style issue. Keep your guide short and sweet so it’s easy for people to reference. Most of our guides include:

• High-level notes about voice and tone
• Usage guidelines
  • Acronyms and abbreviations
  • Capitalization
  • Numbers
  • Punctuation
  • Web styling, such as headers or glossary terms
• Specific words and phrases

Focus on what’s new or particularly unique. If you’re using sentence case or avoiding acronyms, for example, call that out and include inline examples. If you need to use specific terms or technical jargon with users, include suggested phrasing to help other writers follow along.