Hi All. A demo is worth a thousand words so here is a gitbook adaptation of our current documentation[1] (and only documentation) This took me only a couple of hours. There are still things to fix/update/remove like unsupported liquid tags but for the most part, it works like a charm. Search is available from the search field on the top left and PDF[2], epub[3] amd mobi[4] versions are also available. The build took only 10 sec + 10 more per offline version.
The table of content mirrors exactly what we currently have, except that I have limited it to only 2 sub-levels. It means that some pages are missing but I think it demonstrates that our current menu organisation could be vastly improved. Couple of thoughts on Alex's points: > * for the examples, import source code that is actually used in tests (!!!) Indeed, an overhaul does not solve it, nor our current framework. But both can implement it. > * check links Gitbook checks internal links at compile time and refuses to build if something is wrong. AFAIK, there is nothing in the Gitbook world to check the validity of external links like the Jekyll plugin does. There are probably external tools that we can integrate in our build pipeline to cover this. However, it seems that even if we have this tool, we don't use it when pushing the website (as I get a lot of errors locally) Realistically, we will always have broken links, things move around all the time. Checking external links is a nice-to-have but far from being a perfect solution. In any case, I don't see this point as important as you do. > * think through user flow The clear Gitbook menu exposes this pretty well IMO and better compared to the current version so that's a win. Best. [1] https://tbouron.github.io/brooklyn-docs/ [2] https://tbouron.github.io/brooklyn-docs/brooklyn.pdf [3] https://tbouron.github.io/brooklyn-docs/brooklyn.epub [4] https://tbouron.github.io/brooklyn-docs/brooklyn.mobi On Thu, 5 Oct 2017 at 12:47 Richard Downer <rich...@apache.org> wrote: > 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 > > > -- Thomas Bouron • Senior Software Engineer @ Cloudsoft Corporation • https://cloudsoft.io/ Github: https://github.com/tbouron Twitter: https://twitter.com/eltibouron
