Welcome and update on the logistics of the dev room
LF Energy SEAPATH is an open source, high-availability real-time platform designed for hosting virtualized protection and control applications within electrical substations. As a complex project bridging electrical and computer engineering, it integrates multiple open source tools and expertise from diverse domains. Following the recent release of version 1.0, the project undertook a refactoring of its documentation to improve clarity and accessibility for a growing community of users and contributors
This talk will present the documentation strategy for such a complex project, highlighting the challenges encountered and the solutions implemented. Key discussion points include:
Documentation is the backbone of successful projects, yet many tools fall short in balancing ease of use, collaboration, and flexibility. https://github.com/suitenumerique/docs is an open source, block-based editor designed to solve these challenges. Built by the French and German govs, it offers a snappy editing experience, real-time collaboration, fine-grained access control, and powerful features like sub-docs and a headless CMS API. This talk will demonstrate why Docs is the ideal tool for teams looking to create, manage, and scale their documentation effortlessly.
Sometimes you need to mark up what Markdown doesn’t. It’s tempting to pick up a heavyweight Markdown variant, such as MDX, or to build your own just-this-once extension. But extensions to Markdown are often eye-wateringly ugly, fragile, and prone to lock-in. What’s to be done, switch formats? No, you’re too busy for that.
In this talk, I’ll teach you about the little-used extension points that already exist in mainstream Markdown flavors, such as CommonMark, and how to take advantage of them before going off the beaten path. In this talk, you’ll learn about:
Daniel D. Beck is a documentation consultant who helps software engineering teams make tools, processes, and content that reach developer audiences. His talk draws from experience as a longtime contributor and maintainer of open source software and documentation, including as a current maintainer of Baseline, a browser compatibility tool, and a past role as technical content lead for MDN Web Docs.
Docling is an open source toolkit that simplifies document processing by converting various formats like PDFs and Word documents into structured, searchable data. It can handle complex layouts, tables, code, and formulas to preserve the meaning of the data and maintain the formats and relationships of the information. Find out how you might include Docling in your documentation workflow to emcompass diverse documentation sources and formats - including images and audio. As gen AI and LLMs are changing the way we document things and retrieve info, the importance of quality structured data cannot be understated.
You've perfected your Docs-as-Code pipeline. Your HTML documentation is beautiful, version-controlled, and deploys instantly. Then someone asks for a printing version. Printing? What is it? Ah, a primitive pre-HTML way of publishing, no problem... until you try it.
This talk addresses the fundamental mismatch between the web's fluid layout and the paged, fixed-layout world of print. After creating Asciidoctor to Open Document converter (https://github.com/CourseOrchestra/asciidoctor-open-document) I was so stuck in this mismatch that I nearly concluded print output from simple markup was just a toy, and that achieving quality was impossible.
Luckily, I found inspiration in Pandoc's architecture, which acts as a "metaconverter" -- a factory for building converters. Based on its ideas I completely rewritten Asciidoctor to Open Document converter into Unidoc Publisher (https://github.com/fiddlededee/unidoc-publisher). This worked excellently and now I can share my experience in this field.
I will then map the landscape of rendering solutions. We will compare the core options, which are limited to:
There's no silver bullet, there is just a sensible path. Hope this talk will help to choose the right solution for your needs.
The addition of a new Extensions SDK in Superset led to a new initiative: a Developer Portal.
That, in turn, gave us the chance to re-imagine how we WANT our docs to work: • Bringing in scattered readmes/wikis/etc. under one roof • Creating independently versioned areas for different release cycles and intents • Automating screenshots and content to "keep up" with the codebase • Bringing API docs, React Story book, and more into a centralized interactive portal • Leveraging AI to build and maintain docs... for people AND for humans • Syndicating content from third party sources to be the end-all-be-all of Superset documentation • Leveraging AI (for free!) to provide chat-based support AND learn where our docs are falling short from the result
We've learned a lot of hard lessons over the years, and we're happy to share the process, ideas, and tools we've used to take things to the next level.
Documentation often lags behind code changes, leading to inconsistencies and outdated information. This session explores how to automate the generation of comprehensive and up-to-date documentation using a custom Yaml-based domain-specific language alongside Asciidoctor and Antora. By defining product behavior in a DSL, we not only produce the framework for software code but also generate the bulk of the documentation, making the DSL the single source of truth for the project. We'll discuss the power of this approach in keeping documentation aligned with the codebase and also demonstrate how to test code snippets within your documentation. Learn how this practice prevents broken examples and leverages Asciidoctor's capabilities to ensure your documentation remains reliable and accurate.
We introduce a workflow engine that automates and documents complex shell-based tasks in software development. By capturing command sequences as reproducible workflows, the tool reduces technical debt and significantly facilitates maintenance across long-lived projects.
Common use cases include wrapping Yocto and Buildroot builds, automating Linux kernel testing and debugging, and supporting routine IT, network, and infrastructure operations.
In this interactive talk, we demonstrate (live) how the tool:
builds and documents a more general procedure of cross-compiling the Open Source Software firmware for Broadcom's bcm5719 NIC chip than currently available,
automates generating PDF documentation of this procedure,
facilitates sharing this procedure and its documentation in a public or commercial context.
Attendees will learn how to transform hard-to-follow shell scripts into reproducible workflows that produce better documentation and improve collaboration.