Report for my GSoD'20 project: Update how the Kubernetes website serves API references #25404
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Update how the Kubernetes website serves API references
k8s-ci-robot
added
cncf-cla: yes
k8s-ci-robot
added
language/en
|
/assign @zacharysarah |
|
✔️ Deploy preview for kubernetes-io-master-staging ready! 🔨 Explore the source changes: 4b8e1d0 🔍 Inspect the deploy logs: https://app.netlify.com/sites/kubernetes-io-master-staging/deploys/5fcaeffdaf61220008cbc960 😎 Browse the preview: https://deploy-preview-25404--kubernetes-io-master-staging.netlify.app |
sftim
reviewed
Dec 4, 2020
content/en/blog/_posts/2020-12-04-gsod-2020-improving-api-reference-experience.md
Outdated
Show resolved
Hide resolved
content/en/blog/_posts/2020-12-04-gsod-2020-improving-api-reference-experience.md
Outdated
Show resolved
Hide resolved
content/en/blog/_posts/2020-12-04-gsod-2020-improving-api-reference-experience.md
Outdated
Show resolved
Hide resolved
content/en/blog/_posts/2020-12-04-gsod-2020-improving-api-reference-experience.md
Outdated
Show resolved
Hide resolved
content/en/blog/_posts/2020-12-04-gsod-2020-improving-api-reference-experience.md
Outdated
Show resolved
Hide resolved
content/en/blog/_posts/2020-12-04-gsod-2020-improving-api-reference-experience.md
Outdated
Show resolved
Hide resolved
content/en/blog/_posts/2020-12-04-gsod-2020-improving-api-reference-experience.md
Outdated
Show resolved
Hide resolved
content/en/blog/_posts/2020-12-04-gsod-2020-improving-api-reference-experience.md
Outdated
Show resolved
Hide resolved
content/en/blog/_posts/2020-12-04-gsod-2020-improving-api-reference-experience.md
Outdated
Show resolved
Hide resolved
content/en/blog/_posts/2020-12-04-gsod-2020-improving-api-reference-experience.md
Outdated
Show resolved
Hide resolved
Thanks for this review |
|
preview LGTM |
k8s-ci-robot
added
the
lgtm
|
LGTM label has been added. Git tree hash: 74434bdf819e2ca7b88c1a3de2a65419fd8451d6
|
kbhawkey
reviewed
Dec 4, 2020
content/en/blog/_posts/2020-12-04-gsod-2020-improving-api-reference-experience.md
Show resolved
Hide resolved
kbhawkey
reviewed
Dec 4, 2020
content/en/blog/_posts/2020-12-04-gsod-2020-improving-api-reference-experience.md
Outdated
Show resolved
Hide resolved
k8s-ci-robot
removed
the
lgtm
kbhawkey
reviewed
Dec 4, 2020
|
|
||
| The [Kubernetes documentation website](https://kubernetes.io/docs/home/) is built with Hugo from documentation written in Markdown format in the [website repository](https://github.com/kubernetes/website), using the [Docsy Hugo theme](https://www.docsy.dev/about/). | ||
|
|
||
| The existing API reference documentation is a large HTML file generated from the Swagger specifications of the API, added to the content of the website. |
There was a problem hiding this comment.
To be fair, it may be nice to say that you worked with [started working with] the current API reference.
Instead of focusing on "drawbacks", how about focusing on what you wanted to achieve [your goals].
Something like:
- build individual Markdown pages for the main Kubernetes resources
- reuse the website's assets and theme to build, integrate, and display the reference pages
- create reference pages that are more mobile friendly and accessible to search engines
- create reusable reference content
kbhawkey
reviewed
Dec 4, 2020
|
|
||
| The [Kubernetes documentation website](https://kubernetes.io/docs/home/) is built with Hugo from documentation written in Markdown format in the [website repository](https://github.com/kubernetes/website), using the [Docsy Hugo theme](https://www.docsy.dev/about/). | ||
|
|
||
| The existing API reference documentation is a large HTML file generated from the Swagger specifications of the API, added to the content of the website. |
There was a problem hiding this comment.
nit: The existing API reference documentation is a large HTML file generated from the Kubernetes OpenAPI specification.
kbhawkey
reviewed
Dec 4, 2020
| - `apiVersion` and `kind` display the value, not the `string` type | ||
| - on top of the page, the Go import necessary to use these resources from a Go program is displayed | ||
|
|
||
| When the work is integrated, the API reference will be available at https://kubernetes.io/docs/reference/ |
There was a problem hiding this comment.
Is there room to add a section about "Lessons learned" or "future work"?
kbhawkey
reviewed
Dec 4, 2020
| - the resources are categorized, in the categories Workloads, Services, Config & Storage, Authentication, Authorization, Policies, Extend, Cluster. This structure is configurable with a simple [`toc.yaml` file](https://github.com/kubernetes-sigs/reference-docs/blob/master/gen-resourcesdocs/config/v1.20/toc.yaml) | ||
| - each page displays associated resources at the first level ; for example: Pod, PodSpec, PodStatus, PodList | ||
| - most resource pages inline relevant definitions ; the exceptions are when those definitions are common to several resources, or are too complex to be displayed inline. With the old approach, you had to follow a hyperlink to read each extra detail. | ||
| - some widely used definitions are documented in a specific page (ex ObjectMeta) |
There was a problem hiding this comment.
possible edit: some widely used definitions such as ObjectMeta are documented as an individual page?
|
Happy to give this another |
k8s-ci-robot
added
the
lgtm
|
LGTM label has been added. Git tree hash: 5c71b64898508f6c54d8593f3d4de84f7149ce8d
|
kbhawkey
reviewed
Dec 4, 2020
| I was selected by the CNCF organization to work on the Kubernetes documentation, specifically on the subject of making the API Reference documentation more accessible. | ||
|
|
||
| I'm a software developer, with a great interest in documentation systems. At the end of the 90's, I wanted to invest my time in the Linux community and started translating Linux-HOWTO documents. From one thing to another, I learned about documentation systems and finally wrote a Linux-HOWTO, to help document writers learn the language used at this time for writing documents, LinuxDoc/SGML. | ||
|
|
k8s-ci-robot
removed
the
lgtm
|
Putting a hold specifically so I can review and add an editor's note! /hold |
k8s-ci-robot
added
the
do-not-merge/hold
|
/approve @zacharysarah feel free to unhold when ready |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: sftim The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
k8s-ci-robot
added
the
approved
zacharysarah
suggested changes
Dec 5, 2020
There was a problem hiding this comment.
@feloy Some grammatical and formatting feedback, otherwise a great summary. 🌟
|
|
||
| ## Introduction | ||
|
|
||
| [Google Season of Docs](https://developers.google.com/season-of-docs) brings open source organizations and technical writers together, to spend three months working closely on a specific documentation project. |
There was a problem hiding this comment.
Best practice not to begin a line with a link.
Also, some GSoD projects run longer than 3 months.
Suggested change
| [Google Season of Docs](https://developers.google.com/season-of-docs) brings open source organizations and technical writers together, to spend three months working closely on a specific documentation project. | |
| The [Google Season of Docs](https://developers.google.com/season-of-docs) project brings open source organizations and technical writers together to work closely on a specific documentation project. |
|
|
||
| [Google Season of Docs](https://developers.google.com/season-of-docs) brings open source organizations and technical writers together, to spend three months working closely on a specific documentation project. | ||
|
|
||
| I was selected by the CNCF organization to work on the Kubernetes documentation, specifically on the subject of making the API Reference documentation more accessible. |
There was a problem hiding this comment.
Suggested change
| I was selected by the CNCF organization to work on the Kubernetes documentation, specifically on the subject of making the API Reference documentation more accessible. | |
| I was selected by the CNCF to work on Kubernetes documentation, specifically to make the API Reference documentation more accessible. |
|
|
||
| I was selected by the CNCF organization to work on the Kubernetes documentation, specifically on the subject of making the API Reference documentation more accessible. | ||
|
|
||
| I'm a software developer, with a great interest in documentation systems. At the end of the 90's, I wanted to invest my time in the Linux community and started translating Linux-HOWTO documents. From one thing to another, I learned about documentation systems and finally wrote a Linux-HOWTO, to help document writers learn the language used at this time for writing documents, LinuxDoc/SGML. |
There was a problem hiding this comment.
I'm presuming French, please correct if wrong.
Suggested change
| I'm a software developer, with a great interest in documentation systems. At the end of the 90's, I wanted to invest my time in the Linux community and started translating Linux-HOWTO documents. From one thing to another, I learned about documentation systems and finally wrote a Linux-HOWTO, to help document writers learn the language used at this time for writing documents, LinuxDoc/SGML. | |
| I'm a software developer with a great interest in documentation systems. In the late 90's I started translating Linux-HOWTO documents into French. From one thing to another, I learned about documentation systems. Eventually, I wrote a Linux-HOWTO to help documentarians learn the language used at that time for writing documents, LinuxDoc/SGML. |
|
|
||
| I'm a software developer, with a great interest in documentation systems. At the end of the 90's, I wanted to invest my time in the Linux community and started translating Linux-HOWTO documents. From one thing to another, I learned about documentation systems and finally wrote a Linux-HOWTO, to help document writers learn the language used at this time for writing documents, LinuxDoc/SGML. | ||
|
|
||
| Shortly after, the DocBook language was adopted to write the Linux Documentation. I helped some writers rewrite their documents in this format, for example the Advanced Bash-Scripting Guide. I also worked on the GNU `makeinfo` program to add the DocBook output, making possible to transform *GNU Info* documentation into Docbook. |
There was a problem hiding this comment.
Use active voice.
Suggested change
| Shortly after, the DocBook language was adopted to write the Linux Documentation. I helped some writers rewrite their documents in this format, for example the Advanced Bash-Scripting Guide. I also worked on the GNU `makeinfo` program to add the DocBook output, making possible to transform *GNU Info* documentation into Docbook. | |
| Shortly afterward, Linux documentation adopted the DocBook language. I helped some writers rewrite their documents in this format; for example, the Advanced Bash-Scripting Guide. I also worked on the GNU `makeinfo` program to add DocBook output, making it possible to transform *GNU Info* documentation into Docbook format. |
|
|
||
| ## Background | ||
|
|
||
| The [Kubernetes documentation website](https://kubernetes.io/docs/home/) is built with Hugo from documentation written in Markdown format in the [website repository](https://github.com/kubernetes/website), using the [Docsy Hugo theme](https://www.docsy.dev/about/). |
There was a problem hiding this comment.
Suggested change
| The [Kubernetes documentation website](https://kubernetes.io/docs/home/) is built with Hugo from documentation written in Markdown format in the [website repository](https://github.com/kubernetes/website), using the [Docsy Hugo theme](https://www.docsy.dev/about/). | |
| The [Kubernetes website](https://kubernetes.io/docs/home/) is built with Hugo from documentation written in Markdown format in the [website repository](https://github.com/kubernetes/website), using the [Docsy Hugo theme](https://www.docsy.dev/about/). |
| - `map` fields are indicated. For example the `.spec.nodeSelector` for a `Pod` is `map[string]string`, instead of `object`, using the value of `x-kubernetes-list-type` | ||
| - patch strategies are indicated | ||
| - `apiVersion` and `kind` display the value, not the `string` type | ||
| - on top of the page, the Go import necessary to use these resources from a Go program is displayed |
There was a problem hiding this comment.
Suggested change
| - on top of the page, the Go import necessary to use these resources from a Go program is displayed | |
| - At the top of a reference page, the page displays the Go import necessary to use these resources from a Go program. |
| - `apiVersion` and `kind` display the value, not the `string` type | ||
| - on top of the page, the Go import necessary to use these resources from a Go program is displayed | ||
|
|
||
| When the work is integrated, the API reference will be available at https://kubernetes.io/docs/reference/ |
There was a problem hiding this comment.
Suggested change
| When the work is integrated, the API reference will be available at https://kubernetes.io/docs/reference/ | |
| The work is currently on hold pending the 1.20 release. When the release finishes and the work is integrated, the API reference will be available at https://kubernetes.io/docs/reference/. |
|
|
||
| There are points to improve, particularly: | ||
|
|
||
| - some Kubernetes resources are deeply nested. Inlining the definition of these resources makes them difficult to understand |
There was a problem hiding this comment.
Suggested change
| - some Kubernetes resources are deeply nested. Inlining the definition of these resources makes them difficult to understand | |
| - Some Kubernetes resources are deeply nested. Inlining the definition of these resources makes them difficult to understand. |
| There are points to improve, particularly: | ||
|
|
||
| - some Kubernetes resources are deeply nested. Inlining the definition of these resources makes them difficult to understand | ||
| - the created `shortcode` uses the URL of the page to reference a Resource page. It would be easier for the technical writers if they could reference a Resource by its group and name |
There was a problem hiding this comment.
Suggested change
| - the created `shortcode` uses the URL of the page to reference a Resource page. It would be easier for the technical writers if they could reference a Resource by its group and name | |
| - The created `shortcode` uses the URL of the page to reference a Resource page. It would be easier for documentarians if they could reference a Resource by its group and name. |
|
|
||
| **Author**: [Philippe Martin](https://github.com/feloy) | ||
|
|
||
| ## Introduction |
There was a problem hiding this comment.
Suggested change
| ## Introduction | |
| _Editor's note: Better API references have been my goal since I joined Kubernetes docs three and a half years ago. Philippe has succeeded fantastically. More than a better API reference, though, Philippe embodied the best of the Kubernetes community in this project: excellence through collaboration, and a process that made the community itself better. Thanks, Google Season of Docs, for making Philippe's work possible. —Zach Corleissen_ | |
| ## Introduction |
@zacharysarah Thanks for the review, and the Editor's note :) |
|
/hold cancel |
k8s-ci-robot
added
lgtm
|
LGTM label has been added. Git tree hash: c11c36eff7594d0ff9b047ddf8a6f0fbc595c80c
|
6 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Initial description of the GSoD project: https://developers.google.com/season-of-docs/docs/participants/project-cncf-feloy