[placeholder]
At Squarespace, many of our core products are built on web standards, and our engineers are constantly pushing the boundaries of the web’s capabilities. Occasionally, those boundaries reveal a limitation: an opportunity for the web’s native capabilities to grow. This post is the story of how we found such an opportunity to work with the standards community to improve the web in a way that we – and everyone who uses it – can benefit.
In the fast-paced world of software development, documentation often gets a bad rap. It's perceived as a chore, a necessary evil, and sometimes, unfortunately, an afterthought. But what if writing documentation could be as dynamic and collaborative as writing the code itself? What if it could be simpler to write and more practical to use?
Our teams love relational databases and the benefits ACID properties bring to us as engineers, but they have their limits, especially in horizontal scaling. We had to adopt new database tech across a fleet of highly available services while eliminating as much risk as possible… but how? Enter: change data capture patterning.
On the Unfold team at Squarespace, our mobile releases don't require much in the way of manual intervention or human oversight. In fact, we don’t have to give releases much thought at all.
But, this was not always true. This post is a look into what these non-eventful mobile releases are like, dig into how much more eventful they used to be, and walk through the work it took us to get here.
Recently we introduced a write back cache to our Asset Library. This improvement makes life easier for both our customers and our developers. This post walks through the why, the why not and the how.
The outro recaps what you did – write technical documentation! – and introduces next steps like organizing a collection of documentation, revising existing content, and expanding your technical writing skills by joining the technical writing community.
After completing Parts 1, 2, and 3 of this tutorial, your once blank page now has technical writing – you're officially in the home stretch! Technical writing on a page becomes technical documentation only after you test, edit, and publish the content.
Do not underestimate the exponential payoff that comes from testing and revising content. More than one technical writer can claim that revision has either uncovered bugs in software or improved it.
In my opinion, creating good headings and organizing them in a way that’s helpful to readers is much more challenging than drafting content. So pat yourself on the back for completing Part 2 of this series and making it to Part 3. 👏 👏 👏
However, there are three things that undo exceptional headings and structure in technical documentation: content that is inaccurate, content that’s inconsistent, and content that’s inflated.
Part 1 of this tutorial introduced you to the content types that are most common in technical documentation. You also evaluated a real-life example as a reader, and you may have realized how headings are essential to a good reader experience. It’s because readers on the web do not read – they scan¹ . People actually read 25% slower on the web² and they only read 20% of the content on a page³. (This data is from 2008; I’m scared to know the percentage today.)
In the same way the term “books” includes fiction, nonfiction, and biographies as genres, the term “technical documentation” includes many different content types. But what sets technical documentation apart from books are reader traits. These traits are a result of what the reader does as they read technical documentation – they use the app.
Writing is a learned skill. No one person is a good or bad writer. 🙂 When a colleague asked me to mentor them on technical writing, I searched for a single technical writing article, guide, book, or tutorial that addressed three key things. Since I couldn’t find one, I decided to create a tutorial on technical writing.
Last month we shipped the biggest change to our core website editing experience in ten years: Fluid Engine. This blog post addresses how we arrived at the implementation, in addition to walking through a few technical and user experience issues that were core to the development of this feature.
