From b12d3cb11461a5e1aa7d0611645ecd16e50e7949 Mon Sep 17 00:00:00 2001 From: Philippe Martin Date: Sat, 5 Dec 2020 03:20:42 +0100 Subject: [PATCH] Editor's note + Review --- ...2020-improving-api-reference-experience.md | 20 ++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/content/en/blog/_posts/2020-12-04-gsod-2020-improving-api-reference-experience.md b/content/en/blog/_posts/2020-12-04-gsod-2020-improving-api-reference-experience.md index 62d465a8ac..eebcf32f69 100644 --- a/content/en/blog/_posts/2020-12-04-gsod-2020-improving-api-reference-experience.md +++ b/content/en/blog/_posts/2020-12-04-gsod-2020-improving-api-reference-experience.md @@ -7,19 +7,21 @@ slug: gsod-2020-improving-api-reference-experience **Author**: [Philippe Martin](https://github.com/feloy) +_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 -[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. -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'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. -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/). +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/). The existing API reference documentation is a large HTML file generated from the Kubernetes OpenAPI specification. @@ -74,16 +76,16 @@ Here are the features of the new API Reference to be included in the official do - `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 +- At the top of a reference page, the page displays the Go import necessary to use these resources from a Go program. -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/. ### Future Work 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 +- 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 documentarians if they could reference a Resource by its group and name. ## Appreciation