Thomas-
Had a deeper look -- gitbook has moved things forward a lot. Sounds like
it will let us throw away a lot of our home-grown docs-building and
toc-building code and have good search. Look forward to seeing how it
shapes up with styling and guide-v-website integration.
Best
Alex
On 09/10/2017 09:54, Thomas Bouron wrote:
Thanks Mark.
Regarding maintenance, it will be as easy as the current version. Updating
docs means updating markdown files. Adding/moving pages requires to modify
the `SUMMARY.md` but that's it.
One really cool thing is that Gitbook is a node app: really simple to
install/run compare to our current solution which runs only on an old
version of ruby => no more pain of using different versions of ruby on your
environment.
In terms of feature gaps, Gitbook provides the same or more features than
Jekyll out the box:
- search! That is a big one, not available with Jekyll
- include of external files
- syntax highlighting
- plugins system
- custom theme
Best.
On Sat, 7 Oct 2017, 17:10 Mark McKenna, <m4rkmcke...@apache.org> wrote:
Thomas this looks really clean great work.
How much work do you think it will take to maintain vs our current
solution?
What do you see as being the current feature gaps?
M
On Fri, 6 Oct 2017 at 14:55 Thomas Bouron <thomas.bou...@cloudsoftcorp.com
wrote:
Hi Richard.
Of course, I pushed it to my fork on the branch `experiment/gitbook`[1]
Glad you like it :)
Best.
[1] https://github.com/tbouron/brooklyn-docs/tree/experiment/gitbook
On Fri, 6 Oct 2017 at 13:53 Andrea Turli <and...@cloudsoft.io> wrote:
+1 Thomas, didn't know Gitbook at all (that's why I suggested
readthedocs)
but looks pretty good!
Il 06/ott/2017 15:37, "Richard Downer" <rich...@apache.org> ha
scritto:
Hi Thomas,
I withdraw my previous comments - I looked at ReadTheDocs last year and
was
pessimistic, but it seems that GitBook this year is a different story
:-)
This is worth pursuing IMO. What did you need to do to get this
working?
Did you have to do any work on the brooklyn-docs source - if so could
you
share a link to your repo?
Thanks
Richard.
On 6 October 2017 at 13:18, Thomas Bouron <thomas.bouron@cloudsoftcorp.
com
wrote:
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/6f19475bbc0570a3b9e3d1ae1b75b2
b8ee4b2485b3b41d085c342dff@%3Cdev.brooklyn.apache.org%3E
On 5 October 2017 at 11:23, Thomas Bouron
<thomas.bouron@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
--
Thomas Bouron • Senior Software Engineer @ Cloudsoft Corporation •
https://cloudsoft.io/
Github: https://github.com/tbouron
Twitter: https://twitter.com/eltibouron
