brooklyn-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Richard Downer <>
Subject Re: [PROPOSAL] Split Brooklyn website and documentation
Date Thu, 05 Oct 2017 12:47:10 GMT
Thank you for the research you have done Thomas. I've had similar thoughts
myself. The original goal of our web+docs was to integrate them in such a
way that we had a versioned user guide that integrated perfectly with the
main website. At the time, Markdown tools were relatively immature, with
Jekyll leading the pack (and being the fashionable choice), and very little
in the way of viable apps for generating books with structure and tables of
contents. We did the best we could with the tools we had, but they needed
significant extensions (via Jekyll plugins and build scripting). Those
plugins and scripts have turned into something fairly hairy - IMO we
shouldn't need to have to write this much code[1] to generate a static site
and manual. With hindsight, I would not have argued in favour of this
model. If I do write my book[2] I will most likely be writing it in
ReStructuredText and processing it with Sphinx (and no additional

That said, when I have looked at changing Brooklyn's documentation system,
it has not looked easy. With our home-grown TOC generating code, we're not
off-the-shelf compatible with other systems. Moving to another system, even
if it is Markdown-based, would still involve a lot of manual work changing
our document metadata to the new system, and adapting to replace the Jekyll
plugins and the content that uses them (e.g. syntax highlighting, file
inclusion). Unless you have discovered something I didn't, Thomas, then I
fear this will be a lot of work, mostly manual.

In short, yes I like the idea of replacing our home-grown and
home-maintained code with an existing and supported app, but no I don't
think the effort of a big-bang migration justifies the results *at this

Some things I would support:

- Continued incremental improvements to both the website and the user
guide. IMO we have more problems with the content than with the tooling,
and we can still make a lot of improvements to the usability of our docs
and website without tooling changes.

- Breaking the tight integration between website and user guide. "Fork" the
existing infrastructure but then have two build systems tailored for their
purpose rather than one that tried to meet two different needs. Would allow
the existing stuff to continue to work while opening the door to replacing
the guide tooling and redeveloping the website, independently of each
other, at a future date.

- Evaluating how other systems use metadata to describe the book structure,
and gradually adding support for this to our own tools and migrating
content. Then at a later date, when the content is nearly-compatible with
GitBook or some other system, it'll be easier to do the migration.

What do you think? Will following an incremental approach like this allow
us to make improvements gradually rather than a "big bang" replacement of


[1] but
consider the COCOMO figures with appropriate cynicism

On 5 October 2017 at 11:23, Thomas Bouron <>

> Hi all.
> It's been a couple of weeks that I started to look at how to improve and
> simplify the Brookyln website[1]. As I said on the Brooklyn 1.0 thread[2],
> I think we need to sort this out before releasing 1.0.
> I have looked for a framework / library to handle both the website and
> documentation the same way we do it right now. To determine what was the
> best fit, I based my analysis on the following criteria:
> - Able to take markdown files and generate HTML from them.
> - Keep the folder structure intact (currently, pages that seems in the same
> logical group - take pages in the download section[3] menu - jump into a
> different folder/category/section which is very confusing)
> - Be skinnable
> - Able to handle versions for documentation.
> - Able to generate PDF version of documentation.
> - Be as "stock" as possible to limit maintenance and pain during upgrade
> (our current website still uses Jekyll 2.x).
> 2 contenders clearly jumped out from this:
> - Jekyll[4]
> - Gitbook[5]
> ----
> Jekyll
> With the version 3, Jekyll now has a concept of collections[6] which can
> generate pages from markdown files and keep the folder structure.
> The menu can be generated based on this folder structure (with depth
> limitation for example) in combination of some clever liquid tags and
> `include`. However, it will be hard to control the order of items appearing
> on the menu. Another easy solution would be maintain list of links for the
> menu to be generated.
> There are plugins to generate PDF[7], which happens during compile time.
> Finally, Jekyll is highly skinnable with built-in or custom themes.
> ----
> Gitbook
> Gitbook, in its open source version, handles out of the box doc versioning,
> PDF generation at runtime (so it seems) HTML pages generation from
> markdown. The menu is built-in feature, based on a simple markdown list of
> links[8]. This means we need to maintain it but there is a good chance we
> will have to do this with Jekyll as well. Finally, Gitbook is also easily
> skinnable[9].
> ----
> Both frameworks offer mostly the same features. However, Jekyll is easier
> to build a website that looks like a "corporate" one whereas with Gitbook,
> you are "stuck" with the design principals it was created, i.e. serve
> documentation only. But for this very purpose, it is extremely good and
> easy.
> Our website is the combination of both a "corporate website" (i.e. about,
> getting started, community, etc - few pages that describe the project) and
> a documentation.
> Which leads me to my proposal: separate the website from the documentation,
> at least in terms of how we build it. What I mean by this is:
> - Use Jekyll (or even nothing) for the website, except the documentation
> part. This will let us build a nice theme (based on Bootstrap 4 for
> example) without to worry about complicated plugins and custom code for the
> documentation.
> - Use Gitbook for the documentation alone, applying/adapting the theme we
> will create from the point above.
> Best.
> [1]
> [2]
> [3]
> [4]
> [5]
> [6]
> [7]
> [8]
> [9]
> --
> Thomas Bouron • Senior Software Engineer @ Cloudsoft Corporation •
> Github:
> Twitter:

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message