Changing the structure of the section #15164

dockertopia · 2022-07-19T16:19:38Z

Proposed changes

Changes as previously discussed in #14910 (comment)

Related issues (optional)

netlify · 2022-07-19T16:22:04Z

✅ Deploy Preview for docsdocker ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`0c69399`
🔍 Latest deploy log	https://app.netlify.com/sites/docsdocker/deploys/62e166e24dc3fe0009c699dd
😎 Deploy Preview	https://deploy-preview-15164--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

jedevc · 2022-07-20T09:25:49Z

Personally, I would rather we keep the pages together. If we measure pages in screen heights, then for me, then it works out to only around 1-1.5 screens, so I have to click between them to navigate instead of scrolling. I also think most of this information makes sense together in a broad overview - when we dive into the details of how each of these individual parts work, I think we should definitely split then, but maybe not here?

_data/toc.yaml

dockertopia · 2022-07-20T09:46:48Z

Personally, I would rather we keep the pages together. If we measure pages in screen heights, then for me, then it works out to only around 1-1.5 screens, so I have to click between them to navigate instead of scrolling. I also think most of this information makes sense together in a broad overview - when we dive into the details of how each of these individual parts work, I think we should definitely split then, but maybe not here?

We're going to have more content for these pages, and we can get useful analytics if they are sitting in different pages. I honestly think this improves discoverability of content even if we need tweak the placement of some sections. Let's discuss in our next sync.

Co-authored-by: Justin Chadwell <[email protected]>

dockertopia · 2022-07-25T17:02:53Z

As discussed in sync last week.

crazy-max · 2022-07-25T17:20:35Z

build/buildx/index.md

 description: Working with Docker Buildx
-keywords: build, buildx, buildkit
+keywords: build, buildx, BuildKit


keywords should be lowercased to me (cc @usha-mandya @thaJeztah)

Sorry, this was a suggestion by the IDE. Makes sense to have a standard. Just out of curiosity, does it need to be lowercase, i.e., otherwise something is broken?

Good question; I think either way may work, as long as we're consistently using the same.

Looks like the search auto-complete uses them case-insensitive, but it may be that they're used different elsewhere;

"elsewhere" could be as part of an URL and/or anchor, in which case it's possible that they're treated as "different tags". I guess "lowercase" would be the safest option for these 🤔

Ah indeed there is the auto-complete search but I was thinking about search engines and the meta name="keywords" that is case-insensitive. See also #14642 (comment) about keywords meta tag abuse. So might only be relevant for our auto-complete.

So, in your previous example all of them are like Docker, BuildKit, etc.

Comment: I agree that making them all lowercase allows less room for creating multiple like (docker, Docker, dockerfile, Dockerfile) in terms of metadata, in terms of the presentation (they are visible) they make more sense with case. It would be great to decouple that. As in, write them in suitable case (rendering) and them being always interpretated in a case-insensitive way(metadata).

Question for @usha-mandya do we then change all keywords to be lowercase in our docs sets?

@dockertopia Agree on having a standard for keywords. Suggest we use lowercase going forward.

We can create a ticket in the backlog to retrospectively update all keywords to be lowercase. It's not a high priority as the search results are case-insensitive.

Thanks @usha-mandya. Sounds good.

build/buildx/multiarch-images.md

build/buildx/multiple-builders.md

_data/toc.yaml

build/buildx/multiarch-images.md

crazy-max · 2022-07-25T17:25:32Z

build/buildx/multiarch-images.md

+---
+title: Building multi-platform images
+description: Different strategies for building multiplatform images
+keywords: build, buildx, BuildKit, multiplatform images


Suggested change

keywords: build, buildx, BuildKit, multiplatform images

keywords: build, buildx, buildkit, multi-platform images

crazy-max · 2022-07-25T17:27:28Z

_data/toc.yaml

+          title: Working with Buildx
+        - path: /build/buildx/multiple-builders/
+          title: Using multiple builders
+        - path: /build/buildx/multiarch-images/


We should be consistent:

Suggested change

- path: /build/buildx/multiarch-images/

- path: /build/buildx/multi-platform-images/

Needs to rename multiarch-images.md to multi-platform-images.md

It's true. It's called "multi-arch" in Desktop docs, and in conversation we do say multi-arch all the time.
I think most users would equate multi-platform with macOs/Linux/Windows.
And architectures is clear that it refers to HW such as arm, mips, ppc64le, and even s390x.

Also, taking for example this sentence in the original content:
"When you invoke a build, you can set the --platform flag to specify the target platform for the build output, (for example, linux/amd64, linux/arm64, or darwin/amd64)" or this command example "docker buildx build --platform linux/amd64,linux/arm64 "?
We also say "An experimental package is available for arch-based distributions." in Engine doc set.

Just trying to point out that it seems to be a combination of both. Platform is not enough to determine the arch (following the above interpretation): imho multi-architecture being more specific is a better candidate.

Hum right, WDYT @tonistiigi @jedevc @thaJeztah?

I've noticed this inconsistency as well, agreed it would be good to clarify this, but maybe out of scope for this PR, there's a lot of build docs that mix-and-match between the two, so I'd propose to pick something here that works, and then discuss separately later.

Personally, I think multi-platform is better when talking about building images. A couple reasons:

This is what the OCI spec refers to - the CPU architecture is part of the platform (the OS is the other main component).

Buildkit will eventually (hopefully) support building windows images. Say we have an amd64 linux image and a amd64 windows image - in this case, it's not as accurate to talk about multi-arch images, even though the underlying mechanism is the same. Multi-platform is a nice catch-all.

The buildx/buildkit flags are --platform - calling it multi-arch seems like it can be confusing, multi-platform seems more inline with existing behavior.

Maybe there are still use-cases for talking about multi-arch though, for example, maybe around QEMU, when we're using linux throughout, but emulating different CPU architectures.

An experimental package is available for arch-based distributions

I think this is probably unrelated, I think this refers to ArchLinux, not multi-architecture/platform support.

Agreed on the Engine example. I revisited it and @jedevc is right, but a simple docs search renders this

( some are community hits)
And searching multi-platform results in a very different search results list.

It seems for the discussion there's the case for both in content, when platform is the same and we do want to distinguish architectures, but that we'd like to introduce the feature as multi-platform as it's seen as capturing both.

But it leaves the case of harmonizing the remaining docs content.

crazy-max · 2022-07-25T17:34:05Z

_data/toc.yaml

        - path: /build/buildx/install/
          title: Install Buildx
-
+        - path: /build/buildx/


Not sure about the order, looks confusing to me to have the parent page after a subpage.

As I can see with compose it's the first page: https://docs.docker.com/compose/ so we should be consistent.

When we discussed I wasn't aware you saw this whole page as a "Build Overview", sure let's rename that page and reorder the pages, then, so 1) Buildx Overview, 2) Install Buildx for consistency.

Maybe Overview and Install is enough as it's already subpages of Buildx section. Don't think we need to repeat ourselves?

I see what you mean, that there's hierarchy providing context. But when we need to derive it from the folder context and there's multiple in the doc set, I think it's best for any "just" 'overview' or 'install' to be the ones for the main section (so doc set root index or install) for clear disambiguation in a glance.

Empty lines in md. Co-authored-by: CrazyMax <[email protected]>

dockertopia

Left a couple of comments and committed line break removals and lowercased keywords.

dockertopia · 2022-07-25T22:27:15Z

build/buildx/index.md

 description: Working with Docker Buildx
-keywords: build, buildx, buildkit
+keywords: build, buildx, BuildKit


Sorry, this was a suggestion by the IDE. Makes sense to have a standard. Just out of curiosity, does it need to be lowercase, i.e., otherwise something is broken?

dockertopia · 2022-07-25T22:54:37Z

_data/toc.yaml

        - path: /build/buildx/install/
          title: Install Buildx
-
+        - path: /build/buildx/


When we discussed I wasn't aware you saw this whole page as a "Build Overview", sure let's rename that page and reorder the pages, then, so 1) Buildx Overview, 2) Install Buildx for consistency.

dockertopia · 2022-07-25T23:00:19Z

_data/toc.yaml

+          title: Working with Buildx
+        - path: /build/buildx/multiple-builders/
+          title: Using multiple builders
+        - path: /build/buildx/multiarch-images/


It's true. It's called "multi-arch" in Desktop docs, and in conversation we do say multi-arch all the time.
I think most users would equate multi-platform with macOs/Linux/Windows.
And architectures is clear that it refers to HW such as arm, mips, ppc64le, and even s390x.

Also, taking for example this sentence in the original content:
"When you invoke a build, you can set the --platform flag to specify the target platform for the build output, (for example, linux/amd64, linux/arm64, or darwin/amd64)" or this command example "docker buildx build --platform linux/amd64,linux/arm64 "?
We also say "An experimental package is available for arch-based distributions." in Engine doc set.

Just trying to point out that it seems to be a combination of both. Platform is not enough to determine the arch (following the above interpretation): imho multi-architecture being more specific is a better candidate.

jedevc · 2022-07-27T10:36:43Z

_data/toc.yaml

-
+        - path: /build/buildx/multiple-builders/
+          title: Using multiple builders
+        - path: /build/buildx/multiplatform-images/


Suggested change

- path: /build/buildx/multiplatform-images/

- path: /build/buildx/multi-platform-images/

crazy-max · 2022-07-27T10:45:17Z

build/index.md

+
+* **Creating build-once, run-anywhere with multi-architecture builds**
+Collaborate across platforms with one build artifact.  
+See [Build multi-platform images](buildx/multiplatform-images.md).


Suggested change

See [Build multi-platform images](buildx/multiplatform-images.md).

See [Build multi-platform images](buildx/multi-platform-images.md).

(needs to also change filename)

I'm keeping the filename as two words for simplicity in xrefs. I think you'll find it's OK to not reflect the preferred spelling in the name for the file.
We can revisit this later both in terms of style guide (preferred spelling for hyphenated words so it's applied across doc sets) or simple shared guidelines for naming doc source files (even if just recording anything that's been implicit so far).
The idea is whatever points of standardization coming up to be recorded and elevated so there's alignment across teams/doc sets and everyone on the docs teams has an opportunity to be clear on the matter. Again, the is not to dismiss the comments but to address them out of the scope of the PR.

crazy-max

As discussed let's decide what do to for multiplatform vs multiarch vs multi-platform wording and fix references about this in our docs in a follow-up.

Conflict fixes

268391f

dockertopia requested a review from jedevc July 19, 2022 16:19

dockertopia changed the title ~~Changing structure of the section~~ Changing the structure of the section Jul 19, 2022

jedevc reviewed Jul 20, 2022

View reviewed changes

_data/toc.yaml Outdated Show resolved Hide resolved

dockertopia and others added 3 commits July 20, 2022 10:47

Update _data/toc.yaml

c6abbdc

Co-authored-by: Justin Chadwell <[email protected]>

Minor edits regarding split

0173430

Minor edits regarding split, TOC

d469142

Link to new page

4520880

dockertopia marked this pull request as ready for review July 25, 2022 17:18

dockertopia requested a review from crazy-max as a code owner July 25, 2022 17:18

dockertopia requested a review from jedevc July 25, 2022 17:18

crazy-max requested changes Jul 25, 2022

View reviewed changes

dockertopia and others added 2 commits July 26, 2022 00:02

Apply suggestions from code review

4392104

Empty lines in md. Co-authored-by: CrazyMax <[email protected]>

Lowercased all keywords

18bccf8

dockertopia commented Jul 25, 2022

View reviewed changes

Changes from review

7b88125

dockertopia requested review from crazy-max and aevesdocker July 27, 2022 10:18

jedevc reviewed Jul 27, 2022

View reviewed changes

crazy-max requested changes Jul 27, 2022

View reviewed changes

Merge branch 'master' into buildx-newia2

0c69399

dockertopia requested a review from crazy-max July 27, 2022 16:25

crazy-max approved these changes Jul 27, 2022

View reviewed changes

dockertopia merged commit 511c0a0 into docker:master Jul 27, 2022

dockertopia deleted the buildx-newia2 branch September 1, 2022 11:06

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Changing the structure of the section #15164

Changing the structure of the section #15164

dockertopia commented Jul 19, 2022

netlify bot commented Jul 19, 2022 •

edited

Loading

jedevc commented Jul 20, 2022

dockertopia commented Jul 20, 2022

dockertopia commented Jul 25, 2022

crazy-max Jul 25, 2022

dockertopia Jul 25, 2022

thaJeztah Jul 26, 2022 •

edited

Loading

crazy-max Jul 26, 2022

dockertopia Jul 26, 2022 •

edited

Loading

usha-mandya Jul 27, 2022

dockertopia Jul 27, 2022

crazy-max Jul 25, 2022

crazy-max Jul 25, 2022

dockertopia Jul 25, 2022

crazy-max Jul 26, 2022 •

edited

Loading

jedevc Jul 26, 2022

dockertopia Jul 26, 2022 •

edited

Loading

crazy-max Jul 25, 2022

dockertopia Jul 25, 2022

crazy-max Jul 26, 2022 •

edited

Loading

dockertopia Jul 26, 2022

dockertopia left a comment

dockertopia Jul 25, 2022

dockertopia Jul 25, 2022

dockertopia Jul 25, 2022

jedevc Jul 27, 2022

crazy-max Jul 27, 2022 •

edited

Loading

dockertopia Jul 27, 2022 •

edited

Loading

crazy-max left a comment •

edited

Loading

	keywords: build, buildx, BuildKit, multiplatform images
	keywords: build, buildx, buildkit, multi-platform images

	- path: /build/buildx/multiarch-images/
	- path: /build/buildx/multi-platform-images/

	- path: /build/buildx/multiplatform-images/
	- path: /build/buildx/multi-platform-images/

	See [Build multi-platform images](buildx/multiplatform-images.md).
	See [Build multi-platform images](buildx/multi-platform-images.md).

Changing the structure of the section #15164

Changing the structure of the section #15164

Conversation

dockertopia commented Jul 19, 2022

Proposed changes

Related issues (optional)

netlify bot commented Jul 19, 2022 • edited Loading

✅ Deploy Preview for docsdocker ready!

jedevc commented Jul 20, 2022

dockertopia commented Jul 20, 2022

dockertopia commented Jul 25, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thaJeztah Jul 26, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dockertopia Jul 26, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

crazy-max Jul 26, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dockertopia Jul 26, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

crazy-max Jul 26, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dockertopia left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

crazy-max Jul 27, 2022 • edited Loading

Choose a reason for hiding this comment

dockertopia Jul 27, 2022 • edited Loading

Choose a reason for hiding this comment

crazy-max left a comment • edited Loading

Choose a reason for hiding this comment

netlify bot commented Jul 19, 2022 •

edited

Loading

thaJeztah Jul 26, 2022 •

edited

Loading

dockertopia Jul 26, 2022 •

edited

Loading

crazy-max Jul 26, 2022 •

edited

Loading

dockertopia Jul 26, 2022 •

edited

Loading

crazy-max Jul 26, 2022 •

edited

Loading

crazy-max Jul 27, 2022 •

edited

Loading

dockertopia Jul 27, 2022 •

edited

Loading

crazy-max left a comment •

edited

Loading