@ Declarative Amsterdam 2024
2024-11-08

Simplify Your Technical Documentation Workflow with Petal

Alexandra von Criegern, Younes Bahloul, and Adam Retter

tech@evolvedbinary.com
 

github.com/evolvedbinary

Alexandra
von Criegern

Younes
Bahloul

  • Senior Engineer @Evolved Binary

  • Web Development since 2008

  • Developer

    • TypeScript / Node.js

    • XML & XQuery

  • Engineer @Evolved Binary

  • Masters in Computer Vision

  • Developer

    • React / TypeScript / Node.js

    • Java

  • Contributor to eXist-db since 2022

alexandra@evolvedbinary.com
@plutonik-a
younes@evolvedbinary.com
@marmoure

  • An easy way to edit Technical Documentation

  • A WYSIWYG in-browser editor

  • Uses LwDITA (Lightweight DITA) Model

  • Uses our LwDITA library

    • Conversion between XML and JSON

    • Markdown and HTML to be added in future

  • For further details see our XML Prague 2024 talk:

What is Petal?

DITA

Lightweight DITA

(LwDITA)

What is LwDITA?

  • Lightweight DITA

  • An OASIS Standard

  • Expressive subset of DITA

  • Has ~50 elements

  • Multiple authoring formats:

    • XML - XDITA

    • HTML - HDITA

    • Markdown - MDITA

    • JSON - ???

  • Simple!

  • Open an XDITA document

  • Renders an editable representation of the document

  • Allows you to:

    • Edit the text and structure

    • Insert new elements

  • Save the updated XDITA document

What does Petal do?

What's new in Petal?

  • LwDITA Support

    • Updated for compliance with LwDITA 1.0 Draft 7

    • Improved formatting and whitespace handling in XDITA parser and serializer

  • Petal Editor

    • Ability to insert images from via file upload or URL

    • Improved localization and configuration

    • Integration with GitHub

  • Offers an "Edit this page" button

  • Petal Bot - our GitHub App

    • Forks your documentation repository for the contributor

    • Presents the visual editor to the contributor

    • Creates a PR from the contributor back to you

  • You review the contributors PR and merge/reject it

How does Petal integrate with GitHub?

Demo
(A Play in 3 Acts)

Demo - Act 1
An Open Source project needs help with its documentation...

"Edit this page" button

  • Petal API URL parameters

    • ghrepo

      • The GitHub repo. i.e. the “my-org/my-repo” part from "https://github.com/my-org/my-repo"

    • source

      • Location of the document in the repo. e.g. "my-folder/my-doc.dita"

    • branch

      • The git branch

    • referer

      • The web location of the documentation page", e.g. "https://docs.com/my-folder/my-doc.html"

<a href="https://petal.evolvedbinary.com?ghrepo=my-org/my-repo
    &source=my-folder/my-doc.dita
    &branch=main
    &referer=https://docs.com/my-folder/my-doc.html">
  <input type="button" value="Edit this page...">
</a>

Demo - Act 2
A kindly user wants to help improve documentation...

Demo - Act 3
A surprised but happy Open Source project maintainer receives some help...

Summary and Conclusion

  • Petal allows you to edit Documents

  • User's don't need to know XML, Markdown, JSON, or any syntax

  • You don't need to install any tools - just your Web Browser

  • Petal can provide a publishing workflow with GitHub

  • User's don't need to know Git or GitHub

  • XML (LwDITA) at the core for all those good things

    • Such as Single Source Publishing

    • Such as Content Reuse

  • It's Open Source

Roadmap

  • Productisation

    • Polish and Branding

    • Offer Petal as a service

  • Further toolbar buttons for other LwDITA elements

  • Get people using it!

    • Support cityEHR as our first user

    • Write Petal documentation using Petal

    • Use Petal for Elemental's documentation

    • Publicise and Market it

    • Respond to user feedback and requests

Thank You!

Any Questions?

Further information...

Simplify Your Technical Documentation Workflow with Petal

By Adam Retter

Simplify Your Technical Documentation Workflow with Petal

Presentation given for Declarative Amsterdam - 8 November 2024 - Amsterdam

  • 121

More from Adam Retter