None CSS browsers (older safari not on > Sierra OS) doesn't display 'Learn more box' correctly due to lack of support for grid

Add some options from https://gohugo.io/getting-started/configuration/#blackfriday-options

Write up on the Wiki page

https://stage.docs.dotmesh.io/tutorials/hello-dotmesh-docker/

• concepts (introduction & motivation)

Some best practice and re-useables for design would be desirable.

A good start would be

• Toggle, Add and Remove functions (and allow for class changes on $this and $target/s)
• Tabs
• Soft scroll to anchors within a page
• Sticky navigation / waypoints

Please include

tags for text inside the alert for now until I make a shortcode.

https://stage.docs.dotmesh.io/concepts/architecture/#intra-cluster-communications

spacing seems a bit large here, especially between code blocks, can we tighten it up a bit?

Add related content module and get it working with Hugo https://gohugo.io/content-management/related/

currently it looks a bit pants

we might also decide that it's not helpful, in which case we could just bin it.

hello-dotmesh-docker.md links to a Youtube video using oudated branding. Re-record it using the new SaaS skin and update the link in hello-dotmesh-docker.md.

commonly there's a logical "next step" after a page of documentation

It would be cool to have something as nice looking as this, with the "dot-dash" style arrow, for such occasions:

Add something like - https://github.com/ngryman/reading-time - to estimate page reading time

Create final version of glossary with all the nomenclature agreed within Dotmesh.

Now and then, changing things with design.watch running causes the page to re-load many times instead of just once.

I've made this a bit better by pointing the make command at the public folder rather than the whole design folder, but it could do with improving.

We can take guidance on tuning databases for ZFS, such as:

https://blog.2ndquadrant.com/pg-phriday-postgres-zfs/

...and easily convert it into guidance for tuning for Dotmesh.

Currently cannot figure a way with hugos menu options to custom order sub-pages. Appear alphabetically at present.

I've made a custom 404, but we need to get it working. See https://gohugo.io/templates/404/

You can specify subdots with dot.subdot. You can pin branches with dot@branch. How do you pin the branch of a subdot? What does branch pinning even mean? How does this interact with Kubernetes?

I'm wondering if we need a similar command that builds hugo without pulling across everything from design?

I can see a use case for example, where building the hugo site to update the docs doesn't need to pull across all the assets from design, just build new pages within hugo.

as part of docs build

there will be duplication of content in places, e.g. "how to install dotmesh" will appear in the tutorial

It would be nice if we could have these in include files from the get go, so that multiple copies don't end up getting stale and out of date

is gohugoio/hugo#247 (comment) the right way to do this?

Browser sync allows for external and local IP's and ports but this appears to be missing when running in docker.

This is useful for testing on devices, as we can do it locally.

Algolia integration has borked styling a bit across all viewports (seems ok at mid range).

Also, search icon should no longer be a button, as it cannot submit anything

• please can we have a way to (optionally) copy code blocks like this to the clipboard easily? (this is actually rather important)

• we should also track these clicks (click on clipboard icon, or click and drag to copy text even) in segment - they're important, as they indicate that someone is probably following our instructions. it would be good to track pageviews vs clipboard-clicks.

Deliver a solid way of serving fonts across domains, so we can serve them to docs/website/sass and many more platforms if we need to. The fonts should also work locally when developing.

(with diagram, work with Pete), API, supported platforms: Kubernetes (GKE, OpenShift) & Docker (which versions?) installation & integration docs, which OSs?

At the end of each docs page, hopefully someone will have warm fuzzies about something working or having learned something useful. Make the most of this good-will by encouraging them to do something like tweet the page, join our slack and/or register for the dothub.

We'll need to explain how to upgrade Docker and K8s clusters in due course.

I sketched a diagram of the concrete architecture:

concrete-arch-diagram.zip

If somebody who's better at making things look nice than me makes a pretty version, I'll include it in the concrete architecture page!

in case we want to define what dotmesh is in a sentence.

w/sock shop: Docker, Kubernetes

GitHub does a good job of this.

For example, here is a link with some code in it.

And here is some regular, unlinked code.

At the moment, it's impossible to distinguish between linked and unlinked code in the docs.

Needs to look good in the only code is a link case and the there is some code but also some normal text cases.

when i load the api reference page, the syntax highlighting for all the json examples flickers, and then disappears! i want it to stay!

Can't move between pages in a sensible way (Hugo does allow for moving between pages, but seems to only do this based on published data, which is a bit mental)

as part of docs build

Instructions on how to install npm modules within Docker would be great.

Adding the below would improve things in the longer term.
https://www.npmjs.com/package/nunjucks-capture
https://www.npmjs.com/package/gulp-pretty-url

what-is-a-datadot.md demonstrates using Docker Compose, but we could do with a proper guide to doing this.

Write one, and reference it from what-is-a-datadot.md.

Mobile menu has a moment before JS kicks in where it's not collapsed. This could do with some improvement.

in text with a lot of small code blocks, they stand out too much and make the text as a whole harder to read

let's make them more subtle

Copying over from design into Hugo, css appears to get cached. Makes working between design and hugo difficult. We should look to improve this flow

As a documentation author, I want to include transcripts of shell command sequences in documentation with highligthing of important parts, so I can demonstrate how things work directly.

The hugo syntax highlighter isn't the thing for this - a shell transcript is a mixture of shell commands and output from various things in various formats, so no one automatic highlighter can handle it. I'd like to be able to embed raw preformatted text and then manually emphasise parts of it.

hugo/content/api/_index.md contains some examples of a proposed markup for this in the raw pre blocks near the top. Providing CSS to make those pres look like the highlighted content blocks, with a suitable highlight (background colour?) for the em spans would probably do the trick. It might be nice to add a span class for user-entered text (eg, the typed commands) to distinguish them from command output, too?

it would be great to encourage external contributors to fix docs bugs or contribute documentation.

document how to do that, by making pull requests into this repo.

while we're at it, we should probably document this repo's branching structure, which is:

Branching structure for docs repo:
commit all changes to master in advance of the 0.1 release
(this is how kubernetes does it, and it works): when we do future feature (minor/major) releases of dotmesh (on the dotmesh repo's master, creating a release branch when we make the release), we should do the docs repo branching such that master is always what’s live on the docs site at the time, and docs that are going to go into a feature release get made on e.g. release-0.2 and then merged into master when the release is made
this makes it really easy to fix typos in the docs: just commit to master and CI will release them
docs that relate to only certain versions of the OSS releases: rather than complete copies of the docs site for different versions, we should mark features that only work in certain versions in situ e.g. “new in 1.8”
if people really want to go and look at an old version of the docs, they can look at the git history

also formatting:

Formatting docs markdown:
Do not restrict docs to 80 character width on the screen.
It makes diffs harder to read.
Instead, put each sentence on its own line.

we should also clarify content (creative commons) and code (apache 2) licenses.

On /references/api/ page (and maybe elsewhere) the page doesn't finish rendering (no footer etc...). Not sure why that would happen on this page, as it uses the same template as elsewhere (single.html).

Investigate

https://www.npmjs.com/package/hugo-algolia

currently code looks small in headings.

it should look the same size as the heading, like this:

oh boy that's big code!

:)

In api.md, under DotmeshRPC.Get, I have the following:

<dl>

<dt>`Id`.</dt>
<dd>This is just the filesystem ID, exactly as you provided in the request.</dd>

<dt>`Name`.</dt>
<dd>This is the namespace and name of the Dot containing this filesystem.</dd>

This is broken and bad. Please make some shortcodes so I can semantically express the idea of a definition list, and make it expand into something that looks nice and readable. When that's ready, I'll update the API docs to use it!

It would be good to get the public folder to build locally as needed, so I can share a design on something like surge.sh for team reviews, rather than folks needing to pull a repo.

Currently, you need to do this manually using date or lastmod. This doesn't seem ideal