[Outdated] Producing a gitbook out of the patterns in maturity Structured/Validated

[spier]

First experiment of creating a gitbook for #173.

Current demo (Staging version) of this at:
https://innersourcecommons.gitbook.io/innersource-patterns-staging/v/book/

The book is rendered from this this branch:
https://github.com/spier/InnerSourcePatterns/tree/book

I have some further notes on what works well (and what does not) in this approach. Will clean those notes up and then add them here in the coming days.

[spier]

🎉 I got the first fully automatic book generation now, using a GitHub action.
The action reads the patterns from the 2-structured and 3-validated folders and then generates a ToC for gitbook so that the book can be rendered. See sample ToC that is generated here: spier@4a48f07

While doing this I filed #220 and #221 which need to get fixed for the ToC to work. (@lenucksi maybe you can help me with those?)

What is left to do?

• better documentation of how the gitbook generation works (extension of /book/README.md)
• documentation of what gitbook can and cannot do, and which tradeoff decisions I made
• then we should decide together if this is good enough to go live, or what needs to be done before we want to go live

[spier]

Something strange is happening. The GitHub Action works fine on the branch on my fork. However when it runs here on the upstream, somehow it does not work. More to learn about GitHub Actions I guess :)

[lenucksi]

Something strange is happening. The GitHub Action works fine on the branch on my fork. However when it runs here on the upstream, somehow it does not work. More to learn about GitHub Actions I guess :)

Sounds weird. The action you are using is one of the GitHub built ones but does have a repo here. Did you try checking if there's maybe a bug in it that you managed to hit?

[spier]

From my end the book is now in a good enough shape to be released.

Feedback that I need:
The book is now hosted at https://innersourcecommons.gitbook.io/innersource-patterns/v/book/.

Do you like what you see? i.e. is the book good enough to be published for the first time?

• If no, what is missing?
• If yes, I can do most of the remaining work myself but will need help with the merge to master and reconfiguration of the integration between GitHub and gitbook.

Note:
I am still keeping this PR as a draft, because I want to create a new branch for merging into master (cleaner commit messages etc).

Full Details

There are still a couple of content issues in the patterns, however I don't think that we can fix all of them before releasing the book. Instead I hope that we can use the book as a motivation to fix the remaining content issues. It might work like this:

• release the book
• inform all authors that their pattens are now available in the form of a gitbook as well
• if the authors (or other people) spot any issues in the patterns, they can fix them and new versions of the book will automatically be releases as soon as those PRs get merged

New Content in this repo (just for the book)

I added some new content to the repo that is only used for the book, i.e. it addresses the book audience specifically.

• book/Introduction.md - This is the first page the readers see when they enter the book. This is based on our main README.md but adapted to the book audience
• book/contribute-to-this-book.md - Instructions specifically for readers of the book, assuming that they might not even know GitHub at all. These instructions are meant to help the readers fix small typos etc. This was written from scratch, and is pointing to the more detailed instructions in CONTRIBUTING.md and /meta/contributor-handbook.md.

Things to do in order to release the book (1st release only)

• generate a new branch that can be merged more cleanly (fewer commits, better commit message, etc)
  • merge that branch into master on InnerSourcePatterns (upstream)
• reconfigure the gitbook integration
  • build from InnerSourcePatterns (upstream), rather than from spier’s fork
  • release from master branch, rather than from book branch (exclude the book branch)
  • make sure that the GitHub action to generate the ToC works fine on InnerSourcePatterns (upstream)
• (done) cover image
  • create cover image, and upload that to book/innersource-patterns-book-cover.jpg
  • use cover image in the avatar of the book as well
  • add license/attribution of that image
• set up Google Analytics for the book (so that we know how often which pattern gets viewed) - the Analytics that gitbook itself provide are not good enough
• remove the “unlisted” flag from the book
  • while building the book I didn’t want changes to be picked up by the Google Search
  • once we go live, we want to be found i.e. we should remove the “unlisted” flag

Nice to have

• (optional) nicer URLs/domain (see Custom Domain)
  • innersourcecommons.gitbook.io/innersource-patterns/ (once we change to build from the master branch)
  • when we can configure our domain accordingly, we can also use a nicer URL e.g. books.innersourcecommons.org/innersource-patterns/
• (optional) unpublish other gitbooks that were created from the InnerSource patterns repo to make it more clear what the official version is, and to improve the the SEO of the book
  • e.g. Daniel’s experiment - done

[spier]

Closing this PR in favor of #242.