Building help.ubuntu.com

[Doug Smythies]

On 2016.09.26 11:27 Shaun McCance wrote:

> Hi all,

Hi Shaun,

>
> 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?

In terms of a time-line, could I suggest that we leave the already in
progress 16.10 alone. Then we could do some trial work or whatever
as part of the 17.04 cycle, starting early in an attempt to avoid
deadline stress.

In the meantime, would it make sense for you to do a build of
help.ubuntu.com so as to understand what we do today? It would be
pretty simple, as we are just replacing the 16.10 desktop help docs
during remaining updates this cycle. All the other stuff stays the same.

Keep in mind that we (the current doc committers) are more custodians
of workflows that were created before our time than we are experts
on the deep details. In particular, I tend to get lost whenever I
have to dig deep into yelp while investigating some issue.

... Doug