@ 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...