Building help.ubuntu.com

[Shaun McCance]

Hi all,

Currently, if I recall things correctly, help.ubuntu.com is built with
a set of scripts that call yelp-build with the -x option for custom
styling. Rather than have every project roll its own orchestration
scripts, I've been working on a tool called Pintail to manage entire
documentation sites:

https://github.com/projectmallard/pintail

It's built on the same transformations as what you're using now, which
are the same transformations used internally in Yelp. Your custom
styling will transfer to Pintail with little or no modification.

Some of the advantages of switching:

1) It just does all the work of building the site in a single command.
You can trigger this on a webhook for continuous deployment, or you can
publish manually on releases.

2) It understands translations and builds them for you.

3) It knows how to find documents in different git repositories. You
don't have to put all your documents in one repository. Right now, it
only speaks git, but I could teach it about bzr with minimal effort.

4) It can have integrated search built on Elasticsearch. The search is
fully aware of translations, and can keep searches restricted within
documents. So, for example, when you search in the server guide, you
won't get hits from the user guide. You can keep using the Google site
search you're using now instead, but I'd encourage you to at least look
into the integrated search.

5) It's format-agnostic, with different formats and sources handled by
plugins. Right now, it can handle Mallard, Ducktype, DocBook, and
AsciiDoc.

Pintail is just a new layer on top of the tools you're already using,
so it's not a drastic change for Ubuntu. But it would require some ops
work to set it up. I helped a bit in setting up the current publishing
tool chain. I'd be happy to help with this too.

Anybody want to have a chat to explore feasibility?

--
Shaun