Guides for Hanami 2.0

1

General guidelines

  • All the public websites must have the same look and feel.
  • Ideally we should aim to use the same tech stack for all the websites.
  • Use different GH repositories for different websites.
  • Documentation must be written in Markdown.
  • Consider to use automation (e.g. GH Actions) to sync information between the sites.
    • Example: when a new version of Hanami is out, sync the version number across the websites.
  • Automation must happen via team shared tokens, instead of personal ones.
  • The websites must use HTTPS

————————

What to document

  • My assumption is that a newcomer learns a tech following this path: Getting Started, Guides, Docs, API Docs (but only when using the new tech).
  • I’d prioritise following the same order: Guides, Docs, API docs.
  • Getting Started cannot be worked on yet because, it’s subject to the Hanami feature implementations, which we don’t have yet.

————————

Guides

  • It’s fine to take inspiration somewhere else, but remember to put at the top level of the Guides hierarchy what makes Hanami unique. One example are the slices.
  • My suggestion would be to take the existing Guides as base and enhance them with the new Hanami concepts, and with the inspirations taken around.
  • In the structure of this Guides ontology, we should also consider that Hanami 2.0 will support several architectures: monolith (aka slices), micro, and headless. (Names are temporary).
  • The main focus should go to the default architecture: monolith (aka slices).
  • As part of the Guides, it would be nice to have Upgrade Notes from 1.3 to 2.0.
  • The URL to reach the guides must be the same: https://guides.hanamirb.org
  • We should prefix the existing guides to /1.3/ and put the new ones under /2.0/, keeping in mind that we will expand them in the future (e.g. /2.1/ and so on)
  • A user should be able to switch between versions within the UI.
  • The full text search can be still powered by Algolia

————————

Docs

  • We’re currently missing this kind of documentation
  • The goal is to reproduce the same level of granularity that we have in dry-rb (e.g. dry-rb - dry-cli v0.6 - Introduction)
  • That means to explain how a single gem works on its own.
  • There may be overlaps with the Guides, but it’s fine.
  • The URL to reach the Docs could be: https://docs.hanamirb.org (which is currently used for API docs)
  • We should have an entry page that lists all the libraries.
  • Each library page, should have an independent versioned URL for the minor version (SerVer).
  • A user should be able to switch between versions within the UI.

————————

API docs

  • They should bring in one place all the API docs for all the Hanami gems.
  • It should document only public API methods, classes, and modules.
  • We already a script that generates a website, starting from YARDoc code annotations.
  • The URL to reach the API docs could be https://apidocs.hanamirb.org (up to discussion)

————————

Snippets

  • “Learn Hanami by reading, short, curated, manually crafted code snippets .”
  • Snippets are NOT required for 2.0 release
  • They are a way to show short “Hanami recipes” to keep the community curios and creative
    • They are meant to be an ongoing process of creation
  • I’m mentioning them here because we may want to consider to tweak the UI or the tech stack

————————

Tech stack

Operations

  • I would keep the following:
    • Netlify as web hosting
    • DNSimple as DNS hosting and SSL provider
    • CertUP to automatically deploy new SSL certificates from DNSimple to Netlify (it’s a small Heroku app that I wrote)
  • GitHub Actions for the automation

Current stack

  • Main website: Ruby/Middleman
  • Guides: Go/Hugo
  • API docs: Ruby/YARDoc
  • Snippets: Go/Hugo

Quality attributes of the ideal stack

Based on this framework:

  • Performance Efficiency:
    • Time Behavior: elapsed time for building and deploying a website
  • Reliability:
    • Maturity: maturity of the technical solution
  • Maintainability:
    • Modifiability: the degree to which we can customise the solution
  • Portability:
    • Replaceability: the degree to which a solution can be replaced to avoid vendor lock-in
2 Likes
2

In terms of writing guides, I find this blog post by Kathy Sierra to be extremely helpful, drawing a distinction between writing for reference and writing for learning: Creating Passionate Users: Reference vs. Learning: pick ONE

And this one is good too: Creating Passionate Users: Conversational writing kicks formal writing's ass

(I forget where, but @jodosha is the one who introduced me to her work)

1 Like
3

@jodosha Isn’t it a risk, that when we build a Ruby community, and want ruby devs to contribute to our docs and repositories, to use Go-based framework (Hugo) to render those docs?

4

@swilgosz Two thoughts:

  1. I expect the Community to contribute to the contents which are Markdown, not to the site itself.
  2. We’ve been already there: Middleman customizations eventually became unmaintainable to the point that we weren’t able to start the server locally anymore. I had to undo a lot of customizations, in order to get sanity out of it. Hugo doesn’t allow customizations to the engine, only to the templates, which seems a good recipe for long term maintenance.

Do you expect the Community to contribute to the site engine, alongside with the contents?

5

No, you’re right. Contributing to both content and the site happens rarely. When we rewrite the whole framework, and such the whole docs and guides, some changes to the sites will naturally happen in the same time, but it’s not a normal case at all.

1 Like