OpenRiak Website

[Bob-The-Marauder]

We need a website. We have a domain name and I believe that TI Tokyo will provide server space to host it.

Question is, what should we put on it?

Do we want it to be dynamic and flashy like some of the newer databases or do we want a mature look to reflect that our codebase is over a decade old and still good?

Do we want to do like Basho did and just use Wordpress or do we want to do something else e.g. have a Github repo for the website in Markdown that will then be converted. This might allow for easier member contributions but then again, Wordpress isn't that hard either. Do we just want one of those obscenely long web pages that seem to be the trend of late?

Please, ideas, suggestions and anything else you have, drop it in below.

[pjaclark]

As I see it, we need to have a slick, modern feeling website aimed at new users to get people interested. However, we also need all the documentation and history we have on the existing sites for the more technical people.

The page layouts should be simple and clean, but need to be nicely styled. Branding and navigation at the top, footer with links to key site sections and external links (slack, github, social media, etc...).

I'd say use markdown in a Github repo, and either GH pages (not sure if that will let us do fancier things like the documentation version menus or dynamic download pages) or GH Actions with a docker instance running a modern Hugo site generator. Continue using LunrJS for search as that works well.

As a starting suggestion for content:

• www.openriak.com

  • welcome page with key points and links
  • product detail pages for KV, CS and TS
  • "how to" section
    • for both new people and existing people
    • setting up a cluster for testing, development and deployment purposes
    • setting up basic and more advanced features
    • upgrading
  • technical blog
    • best practise guides
    • code dives
    • edge cases
    • in-depth explanations of features
  • help and support options
    • the Slack channel
    • GitHub
    • a list of professional support providers
  • news
    • releases
    • events
    • new blog posts
    • etc
    • RSS feed
  • social media links and invites ("follow us on...")
  • case studies
    • we should aim for at least 4 in different verticals and with different use-cases
    • more case studies is good but variety in use-cases is better
    • case studies can be anonymous/generic
  • archived items
    • the old Riak mailing list (I already have this partially converted to markdown - needs some clean-up but 75% there)
    • the old technical blog posts from riak.com

• docs.openriak.com

  • versioned history of docs updated to use new style
  • move everything before 3.2.x to the "other" section that is hidden by default

• files.openriak.com

  • downloads for all products and versions of OpenRiak and Riak
  • repos for various OSs

[Bob-The-Marauder]

Debating whether it should be files.openriak.com or downloads.openriak.com - maybe have one as a cname of the other?

That said, I like having them separated out. I think, especially given the complexity of the full docs, having docs on a separate subdomain makes a lot of sense. That also allows us to focus on the main website without having to forcibly re-modify the CSS etc of the current docs and package downloads sites, which, for now, I would suggest we do with a quick copy/paste/re-logo from TI Tokyo's ones as they are the most up to date. We can re-jig them or even move to a different system later if/when we have time to do so.

Going forward, I agree that we need to have an attractive main website with simple tutorials to allow most levels of developer to get at least a standalone node running for development purposes. The beauty of Riak/OpenRiak is that if your code works on a single node, it should work equally well on a cluster unless you are doing something incredibly niche. The current docs site along with documentation in Github is a bit high level for new coders experiencing Riak/OpenRiak for the first time. There is invaluable content in there, especially for when it comes to high level system tuning but it is a little non-sequential for those not used to the style many of us more experienced with Riak/OpenRiak write in.

Initial setup speed I think is key here. We need to get as much up as possible while OpenRiak is still in the spotlight or people will think it's yet another false start where movement halts and Riak fades into obscurity again. With the logo vote closing on Sunday, I suggest we at least do the docs and the downloads pages as soon as the logo is decided.

[martinsumner]

I look at two obvious comparators - FoundationDB and CouchDB. Both open-source, niche, NoSQL databases.

What is noticeable is how simple their sites are. I suspect they're simple as they know their audience - my hypothesis is that most enterprise adoption of open-source is led by engineers, and so they speak only to the engineers. Also simple in that it seems to be fairly easy to maintain, nothing that may require an ongoing churn of content. They also focusing on documenting the present & the near future, but not the past.

Most of the documentation is just using standard documentation packages (e.g. sphinx) of github markdown on the project website (presumably to host on github pages).

Overall, I like these examples, and I think we should keep things as simple as possible.

[martinsumner]

One thing on hosting of both the site, and also of production of packages going forward. I think we have to be careful about what assurance can be demonstrated about the integrity of the build chain. If we provide packages going forward, they should be automatically produced through a visible process - maybe Github Actions -> PackageCloud. We have to trust third parties in this case, but third parties which are subject to very strict audit conditions.

For similar security reasons I have a preference for any website to use auto-generation to Github Pages or equivalent, rather than have to trust an unaudited organisation to adhere to sufficiently strict security processes in managing the hosting of a software.

[pjaclark]

Docs, downloads and support for older versions

Docs and support for historical versions is essential as companies do not upgrade unless there is a pressing need. Even then, it's normally an OS upgrade rather than a Riak upgrade which is why we make packages for older OSs. We shouldn't have an "only current" set of documentation and downloads.

Build process

I agree with automating the build process via GitHub Actions -> Package Cloud, and maybe also GitHub's Releases so there is a manual way of downloading packages from a trusted source (which many corporate clients prefer).

The current method of getting packages (files.tiot.jp) has a specific structure that Basho used to automate the creation of download links (as a JSON blob which was then used by Hugo) in the docs. We can probably change that to use the GitHub API for releases instead. I'll have to research how GitHub releases works with multiple OS versions and architectures for a given release tag if we go that route.

We can get a free account with PackageCloud under their "Free for OpenSource" program.

Docs process

I think we're in general agreement here. It would be lovely to have this fully automated.

Would you consider the use of Hugo via docker to make the static files sufficient (in which case this should be fairly simple)? Or would you be keen for a complete rewrite of how the docs get generated from the Markdown source in GitHub using Sphinx? Sphinx's multi-version support seems quite poor compared to what we do now.

My personal preference would be to update to the latest version of Hugo (which will involve some work, but less than migrating to Sphinx) and then doing GitHub repo with Markdown -> GitHub Actions -> Hugo -> GitHub Pages with custom domain "docs.openriak.com". We would then do the same for "www.openriak.com". This also allows for very simple testing during updates.

[martinsumner]

We probably need to check in with Alistair (with his security hat on) what the requirements might be here (e.g. ISO approved accreditation etc), for hosting or building packages associated with the project. There may be some other parts of the process we need to consider, such as the pre-building of binaries (e.g. rebar3) within the repos itself.

Older versions

There is a need to provide documentation for older versions, so this is a question about how this should be done.

Lots of people, including us, use a non-current version of Erlang/OTP; and it is possible to access the documentation of previous versions. However, going to https://www.erlang.org/doc/readme.html still takes you to the current version only, and that is what google indexes etc.

So if it makes life much harder to present all versions together, just as basho did, I don't think we should be tied to that. I'm concerned here not only about the impact on producing the docs, but also on consuming them. I don't want to hamper our ability to refactor the documents to make them easier and clearer to consume now, because of a need to present them in the same visual framework for showing past documentation (when the project had so many more parts).

Likewise for builds. In my opinion we (the OpenRiak community) should focus on having the best process for making packages available to get the current release, on a currently supported OS. If packaging older releases and a wider variety of Operating Systems over-complicates that process, then including that shouldn't be a priority for the community effort. That is not to prevent any third party from fulfilling demand as part of the services they provide, but then how a third party should do that would be between them and the people who use that service; and not a matter of concern to the OpenRiak community.

Doc automation

For me, running a very old version of software because we can't upgrade is a no-no. It is imperative we keep things up to date, and can demonstrate the ability to keep things up to date. Perhaps also, something we should check with Alistair on.

As per above, I would be happy to break the link with past documentation if it makes this easier to do, but others may have a different opinion. If we really want to maintain version history as per-basho docs, and use a common up-to-date documentation framework - someone has already done the bulk of the work and I think we should take advantage of that.

[martinsumner]

With respect to documentation, I wrote up my core concerns about the current content:

OpenRiak/riak#14

I'm not sure we can never edit our way out of this mess. The problems of Riak documentation are too fundamental to fiddle forward with minor changes.

[tburghart]

First, as a general point, I think it's important for the website to be consistently referred to as openriak.org instead of .com - the latter can be a CNAME pointing to the former, but as a community open-source project, .org is the standard TLD and we should follow that norm. I don't think there should be any public references to openriak.com at all. Ideally, as we've discussed elsewhere, I'd like the domains to be registered to EEF in perpetuity.

I agree with Martin, with clarifications of my opinions that:

• The full site should be hosted on GitHub pages from a repo in the OpenRiak project.
• The opening page should be simple, perhaps with top-row links over a brief blurb (a la FoundationDB):
  • About => possibly a pointer to OpenRiak/.github/profile/README.md.
  • Docs => points to docs.openriak.org.
  • Source => points to github.com/OpenRiak.
  • Download => points to a page offering:
    • Source tars produced by GH release action.
    • Courtesy pointer(s) to external package provider(s) with a disclaimer that the OpenRiak project doesn't support them (i.e. complain to the package provider, not us).
  • Support => points to a page offering:
    • Reference to the slack channel postriak.slack.com.
    • How to open issues on the repos.
    • Courtesy pointer(s) to external support provider(s).
• docs.openriak.org is generated automatically via GHA using up-to-date tools.
  • Default page is for the current version.
  • Links for prior versions.
  • Link to Lee's ChatGPT thingy.

You'll note that I want to keep us at arms length from commercial entities, which I believe to be critical for corporate adoption and participation. I'm happy to have TIoT (or any other company) participating, but I don't want us to show any official or implied preference for any external vendor. Again, I want to stress that we're a community-supported project and, like many, you can purchase services from external vendors, but that's your own business decision and entirely distinct from the OpenRiak project.