Session
FOSDEM Schedule 2021
Tool The Docs

An documentation workflow loved by both Data Scientists and Engineers

Using Pandoc with VCS and CI/CD
D.docs
Colin Dean
<p>I observed a white paper authoring collaboration workflow problem at my Forbes 50 employer wherein a tedious workflow around legacy tooling caused undue stress, headaches, rework, and, ultimately, a cosmetically poor-looking document with inconsistent content and styles. Knowing that a good document requires both good content and presentation, I proposed and led the creation of a simple workflow amenable to our team's software engineers and data scientists: treating the white paper text as code with technologies including Markdown, GitHub Enterprise, Pandoc, LaTeX, and a review process that gets the tooling out of the way in order to enable content authors to focus less on logistics and more on writing and reviewing. The result was that a team of seven engineers and data scientists created a 50-page document containing text, diagrams, equations, graphics, and more in just two weeks. The result greatly pleased our directors and executives. They praised our team not only for the incredibly valuable content but also for the professional appearance of the document. When they learned about the peer review process we used to create it, they wanted more teams to use it.</p> <p>This talk focuses on the problems of passing around files by email or shared drives, the problems of collaborative editing of online documentation, and the problems we're still addressing in our solution that we've now used to author several significant internal documents.</p>

Additional information

Type devroom

More sessions

2/7/21
Tool The Docs
Gaurav Nelson
D.docs
<p>Learn about the missing ingredient from your Docs-as-Code recipe, a headless CMS (Content Management System). Let's understand the problems writers face and how adding a CMS to your Docs toolchain helps solve (some of) them. We'll look at a sample docs-as-code repository and then add a CMS to the mix. We'll then go through authoring new topics and editing existing docs with our CMS (Look ma, no Git).</p>
2/7/21
Tool The Docs
Divya Mohan
D.docs
<p>Originally having been developed for the open source projects at Facebook, Docusaurus now serves as an easy-to-use tool across many open-source projects. Having worked with it on the Google Season of Docs for transforming Rucio's documentation (http://rucio.cern.ch/documentation/) &amp; as the SIG DOCS lead for LitmusChaos, this talk is an exposition of my experiences with the static site generator. I hope to benefit others looking at migrating to/using this tool with the contents.</p>
2/7/21
Tool The Docs
Ralf Müller
D.docs
<p>The combination of AsciiDoc and Gradle should be well known by now. But what if you want to go beyond? Have you ever tried to include UML diagrams the easy way, convert Excel to AsciiDoc or export your results to Confluence? This talk shows you what you can really do if you treat your docs as code and apply some tricks you only did to your code before. Forget about copy &amp; paste your images to your documentation – let the build do it! Create different docs for different stakeholders and ...
2/7/21
Tool The Docs
Alexander Schwartz
D.docs
<p>The tool Antora creates documentation websites from AsciiDoc sources stored in Git repositories. Users can browse the generated website and select the version matching the software they use. Navigation outlines, search and cross-references between pages allow users to find answers to their questions. Several open-source software projects like Camel, Debezium and Couchbase use this solution.</p>
2/7/21
Tool The Docs
Ben Greenberg
D.docs
<p>In 2017 Nexmo (now Vonage) launched their first documentation portal as a Ruby on Rails site. Fast forward more than 3 years and the Vonage API Developer is now running on a custom-built open-source tool we call Station. Station powers multiple documentation portals, and allows us to achieve numerous organizational goals.</p> <p>How did we arrive at Station and not get derailed in the process?</p> <p>In this talk, we will take a deep dive into the technical journey behind Station. What does ...
2/7/21
Tool The Docs
Peter Eisentraut
D.docs
<p>PostgreSQL has been maintaining its documentation in DocBook for over twenty years. It's been successful but not without challenges. PostgreSQL is often praised for its excellent documentation, and PostgreSQL is also often criticized for its hard-to-approach documentation.</p>
2/7/21
Tool The Docs
Nicolas Massart
D.docs
<p><a href="https://github.com/tcort/markdown-link-check">Thomas Cort link checking suite</a> is Node.js software to make the checking of links in documentation sites (and not only doc) easy and efficient. It can be used as a standalone or in a CI process. It's configurable and of course as an open source project, you can customise and participate by pushing Pull Requests. As one of the maintainers of this tool suite, I will provide an overview of the link checking process as well as a tour of ...