Structured writing has never been more important, or more confusing. We keep trying to do more and more with content and give ourselves less and less time to do it. Structured writing can help keep our rhetoric on track and our processes efficient. But how does it do that and what is the relationship between rhetoric and process?

It is easy to get lost in sea of acronyms and buzzwords: semantics, XML, metadata, DITA, structure, DocBook, hypertext, Markdown, topics, XSLT, reuse, LaTeX, silos, HTML. This talk cuts through the noise, explaining what structured writing is (you have been doing it all along) and how different structures are used to achieve different purposes.

Most canned structured writing systems are all about process and can actively get in the way of good rhetoric. Deliberately avoiding the discussion of any particular structured writing system, this talk focuses on showing how structured writing can be used to improve rhetoric and how a focus on rhetoric can enhance process as well. It shows how the right structured writing techniques can improve the quality of your content and make your content process more efficient at the same time, without having to sacrifice quality for efficiency or vice versa.

Who cares about content? Everyone who touches an open source project! The community can’t contribute to a project they don’t understand. But writing documentation isn’t enough: you need a content strategy that defines how the content will be structured, written, tested, and updated along the way as contributions come in. If there is no proper process in place, you are going to be in one hot mess.

In this session, attendees will learn:

• What’s in store for open source technical documentation
• The people and technology needed to help you create open source documentation
• What matters most: quantity over quality or quality over quantity?
• What it takes to have open source documentation that drives customer satisfaction
• Making the process work for your organization with every contribution

This talk will cover best practices on how to create documentation that can be within reach to individuals who might not have ever thought they would be writing code before and why accessible documentation needs to be a part of the conversation around diversity and inclusion.

We’ll get started by defining what accessible documentation looks like. We’ll also cover what common pitfalls exist and how to prevent falling into these traps such as talking in jargon and assuming a base of experience that isn’t defined. We will also dig into code examples in documentation and discuss what context is needed to ensure that these are reachable to all. This talk will conclude with a checklist of what you need to make your documentation accessible to all.

When we choose to manage docs like code, we gain a variety of options for where to store the “source” files of those docs, and how they interact with the code they document. The question then becomes, how do we choose among these options? Do we store docs in the code, near the code, or in a separate location altogether? What are the implications of these choices, for the docs themselves and for the people who maintain them?

Open source projects provide a great source for guidance on these questions, because their docs, their code, and the evolution of the processes used to create both are open for public viewing. As a documentarian working on a number of open source projects, as well as providing site deployment support to even more, I’ve seen and tried a variety of strategies, and learned from both successes and failures.

I’ll cover the benefits and challenges of different approaches, give examples of specific projects using each approach, and detail the docs evolution of a single open source project, Netlify CMS, as we moved through different strategies to meet changing needs and unexpected challenges. You’ll leave with guidelines for choosing the best “path” for your current and future docs-as-code projects, along with exemplars to consult for guidance when you make your choice.

We have never written documentation for just one audience, and we have never been able to count on our product name staying the same. Back when we were in Kansas, we had powerful writing IDEs to manage these problems. But now that we're in Oz, docs are code and code is documentation, and it all seems very different. Follow along with me as we explore some use cases and lesser-used code tools to deliver our users exactly the documentation they need, no more and no less. That's a horse of a different color!

This talk will briefly touch on toolchains and workflows that peaked when we were still delivering help with software, and extrapolate how we can use modern code practices and deployment styles to replicate the best parts. These will include universal variables, tying documentation delivery to the version of the product provided, and allowing users to select what they want help with.

Free and Open Source projects are notorious for incomplete and poorly written documentation.

GitHub's 2017 Open Source Survey found that "documentation is highly valued, but often overlooked" with 93% of respondents agreeing that "incomplete or outdated documentation is a pervasive problem."

In attempt to solve that problem, many free and open source software projects try to make doc writing easier, quicker, and less formal — using wikis, lightweight site generators, and Markdown. Some people claim that this enables "non coders" (that is, people who aren't familiar with command lines and version control systems) to contribute.

This is a mistake.

Any project larger than a small utility library needs real documentation tools. "Quick" and "easy" tools like wikis and Jekyll blogs contribute to documentation debt as organizing, editing, and adding content slowly become more onerous and disconnected from the developer experience.

The solution is Docs like Code — treating your documentation like a first class product, an engineering product. By not ignoring the lessons we've learned about how communities write, test, and deploy code together, we can get better at writing, testing, and deploying documentation together.

Additionally, far from scaring off "non-coders", this approach encourages potential contributors to learn basic open source contribution skills in a less complicated, easier to understand context. Since documentation isn't actually code, a Docs as Code process provides a relatively low barrier for people to learn and practice all the non-coding skills needed for open source participation.

Highlighting the documentation process at Open Data Kit, and featuring ideas from several other open source documentation projects, this talk will explore how using the common tools, processes, and platforms of modern open source development — git, GitHub, automated testing, continuous integration — fosters the production of high quality documentation and empowers new open source contributors.

In May 2018, the Kubernetes special interest group for documentation (SIG Docs) migrated the Kubernetes website's static site generator from Jekyll to Hugo. Three of SIG Docs' fifteen core maintainers made a proposal that affected thousands of contributors to the Kubernetes project.

Starting from an initial conversation in late February, 2018, the core group of SIG Docs maintainers debated if migrating was the right move, came to consensus, created a doc assessment for the site, communicated the impact of the migration to other Kubernetes stakeholders, migrated the site to its new infrastructure, and did post-migration cleanup. From proposal to execution, the process took three months.

The focus of this talk is on effective decision making in large scale, open source projects. We’ll discuss:

• Why SIG Docs decided to migrate the site's infrastructure
• How we propose and discuss large-scale projects
• How we communicate as a team
• How we get to consensus as a group, and what consensus means to us
• How we informed the larger organization
• How we decided when to migrate
• How we communicated what we did
• What the migration experience was like
• What went well, and what we wish had gone better
• Where we're headed next

Along the way, we'll discuss some technical specifics of Jekyll and Hugo. We'll also talk about how to get things done when mistakes carry seven-figure price tags.

Kubernetes is an open-source software project for orchestrating container deployment. For more information, visit https://kubernetes.io (which we are pleased to say loads now more quickly and reliably).

As an engineer dedicated to improving the safety of autonomous vehicles, I am beholden to the automotive industry’s standard used for certifying functional safety for EE systems — ISO 26262. The purpose of this standard is to minimize the risk of harm by enforcing a structured, rigorous product development process. This means that before a component can be integrated into a vehicle, it must be certified as compliant with the aforementioned standard.

Complying with ISO 26262 is a meticulous and arduous process, by design. To satisfy this traditionally bureaucratic behemoth, extensive amounts of very specific documentation must be furnished as evidence that the requirements of the standard were strictly adhered to. The scope and purpose of this evidence vastly exceeds that of the documentation done in a typical software development process. To maintain efficiency and flexibility while developing our software, we knew we’d need to lean into automation to grapple with this beast.. Our goals are specific to automotive, but we predicted the resulting tools and processes would be valuable to providing consistency and verifiability to any project. One facet of facilitating this goal that we’ve pursued---and is covered by this talk---is a specification for constraining Markdown document structure and a tool created for validating it.

With an ever-present need to prove value to the organization, I found myself struggling to get the data I needed to put together an argument based on fact, rather than anecdotes. In this session, I’ll take the anecdote of my situation and show how analytics enabled my team to pull forward, get executive buy-in, enable process change and succeed. Over the course of the session, I’ll delve into three primary questions and propose where you’ll find some answers.

• What are some of the metrics you might want to find?
• What are your baselines?
• What happens if the data doesn’t tell you what you expected?

What your users are telling you about how they access your content can tell you volumes about roads to improve all aspects of user assistance.