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 scripting/tooling!).
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 time*. 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 tooling? Richard. [1] https://gist.github.com/rdowner/a09a268b37904a03c452797e7afe56ca but consider the COCOMO figures with appropriate cynicism [2] https://lists.apache.org/thread.html/6f19475bbc0570a3b9e3d1ae1b75b2b8ee4b2485b3b41d085c342dff@%3Cdev.brooklyn.apache.org%3E On 5 October 2017 at 11:23, Thomas Bouron <thomas.bou...@cloudsoftcorp.com> wrote: > 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] https://brooklyn.apache.org/ > [2] > https://lists.apache.org/thread.html/dae4468aa7ef77af9dc8aca24b8434 > e9782efbd50fa876618cccf980@%3Cdev.brooklyn.apache.org%3E > [3] https://brooklyn.apache.org/download/index.html > [4] https://jekyllrb.com/ > [5] https://github.com/GitbookIO/gitbook > [6] https://jekyllrb.com/docs/collections/ > [7] http://abemedia.co.uk/jekyll-pdf/ > [8] https://toolchain.gitbook.com/pages.html > [9] https://toolchain.gitbook.com/themes/ > -- > > Thomas Bouron • Senior Software Engineer @ Cloudsoft Corporation • > https://cloudsoft.io/ > Github: https://github.com/tbouron > Twitter: https://twitter.com/eltibouron >
