From eda601a4e257be86b3e0dfbd78fa5bccdfcda532 Mon Sep 17 00:00:00 2001 From: Philippe Martin Date: Thu, 3 Dec 2020 19:13:38 +0100 Subject: [PATCH 1/8] Report for my GSoD'20 project Update how the Kubernetes website serves API references --- ...2020-improving-api-reference-experience.md | 81 +++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 content/en/blog/_posts/2020-12-04-gsod-2020-improving-api-reference-experience.md 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 new file mode 100644 index 0000000000..dc13b05926 --- /dev/null +++ b/content/en/blog/_posts/2020-12-04-gsod-2020-improving-api-reference-experience.md @@ -0,0 +1,81 @@ +--- +layout: blog +title: "GSoD 2020: Improving API Reference experience" +date: 2020-12-04 +slug: gsod-2020-improving-api-reference-experience +--- + +**Author**: Philippe Martin + +# 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 during the autumn 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'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. + +# 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 API reference documentation is a large HTML file generated from the Swagger specifications of the API, added to the content of the website. + +This API reference has some drawbacks: +- it is a single huge HTML page containing all the API reference +- its format is not adapted to mobile reading +- its design is not integrated with the kubernetes.io/docs website +- its content cannot be referenced by search engines + +On my side, I wanted for some time to make the API Reference more accessible. Around one year ago, I started to work on the generator building the current unique HTML page, to add a DocBook output, so the API Reference could be generated first in DocBook format, and after that in PDF or other formats supported by DocBook processors. The first result has been some [Ebook files for the API Reference](https://github.com/feloy/kubernetes-resources-reference/releases) and an auto-edited paper book. + +I decided later to add another output to this generator, to generate Markdown files and create [a website with the API Reference](https://web.archive.org/web/20201022201911/https://www.k8sref.io/docs/workloads/). + +When the CNCF proposed a project for the Google Season of Docs to work on the API Reference, I applied, and the match occurred. + +# The Project + +## swagger-ui + +The first idea of the CNCF members that proposed this project was to test the [`swagger-ui` tool](https://swagger.io/tools/swagger-ui/), to try and document the Kubernetes API Reference with this standard tool. + +Because the Kubernetes API is much larger than many other APIs, it has been necessary to write a tool to split the complete API Reference by API Groups, and insert in the Documentation website several `swagger-ui` components, one for each API Group. + +Generally, APIs are used by developers by calling endpoints with a specific HTTP verb, with specific parameters and waiting for a response. The `swagger-ui` interface is built for this usage: the interface displays a list of endpoints and their associated verbs, and for each the parameters and responses formats. + +The Kubernetes API is most of the time used differently: users create manifest files containing resources definitions in YAML format, and use the `kubectl` CLI to *apply* these manifests to the cluster. In this case, the most important information is the description of the structures used as parameters and responses (the Kubernetes Resources). + +Because of this specificity, we realized that it would be difficult to adapt the `swagger-ui` interface to satisfy the users of the Kubernetes API. + +## Markdown pages + +The second stage of the project has been to adapt the work I had done to create the k8sref.io website, to include it in the officiel documentation website. + +The main changes have been to: +- use go-templates to represent the output pages, so non-developers can adapt the generated pages without having to edit the generator code +- create a shortcode, to easily create links from inside the website to specific pages of the API reference +- improve the navigation between the sections of the API reference +- add the code of the generator to the Kubernetes GitHub repository containing the different reference generators + +All the discussions and work done can be found on [this Pull Request](https://github.com/kubernetes/website/pull/23294). + +The Pull request to add the code of the generator to the Kubernetes GitHub repository is [this Pull Request](https://github.com/kubernetes-sigs/reference-docs/pull/179). + +Here are the features of the API Reference included in the official documentation website: + +- 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 at the first level the associated resources, for example Pod, PodSpec, PodStatus, PodList +- each resource inlines its definitions (except when definitions are common to several resources, or are too complex to be displayed inline) +- some widely used definitions are documented in a specific page (ex ObjectMeta) +- required fields are indicated, and placed first +- fields of a resource can be categorized and ordered, with the help of a [`fields.yaml` file](https://github.com/kubernetes-sigs/reference-docs/blob/master/gen-resourcesdocs/config/v1.20/fields.yaml) +- maps fields are indicated (ex pod.spec.nodeSelector 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 + +# Appreciation + +I would like to thank my mentor [Zach Corleissen](https://github.com/zacharysarah) and the lead writers [Karen Bradshaw](https://github.com/kbhawkey), [Tim Bannister](https://github.com/sftim) and [Qiming Teng](https://github.com/tengqm) who supervised me during all the season. They all have been very encouraging and gave me tons of great advices. From 4b49c9accb74d5b85e474adfb5e22e603e3b6785 Mon Sep 17 00:00:00 2001 From: Philippe Martin Date: Fri, 4 Dec 2020 11:48:58 +0100 Subject: [PATCH 2/8] add link to github --- .../2020-12-04-gsod-2020-improving-api-reference-experience.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 dc13b05926..5377f9f7bb 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 @@ -5,7 +5,7 @@ date: 2020-12-04 slug: gsod-2020-improving-api-reference-experience --- -**Author**: Philippe Martin +**Author**: [Philippe Martin](https://github.com/feloy) # Introduction From 72b62dd3dd9cb111e2a299f4712d4204f8aa577e Mon Sep 17 00:00:00 2001 From: Philippe Martin Date: Fri, 4 Dec 2020 12:07:46 +0100 Subject: [PATCH 3/8] review --- ...2020-improving-api-reference-experience.md | 26 ++++++++++--------- 1 file changed, 14 insertions(+), 12 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 5377f9f7bb..f29242986f 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 @@ -1,6 +1,6 @@ --- layout: blog -title: "GSoD 2020: Improving API Reference experience" +title: "GSoD 2020: Improving the API Reference Experience" date: 2020-12-04 slug: gsod-2020-improving-api-reference-experience --- @@ -21,7 +21,7 @@ Shortly after, the DocBook language was adopted to write the Linux Documentation 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 API reference documentation is a large HTML file generated from the Swagger specifications of the API, added to the content of the website. +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. This API reference has some drawbacks: - it is a single huge HTML page containing all the API reference @@ -47,35 +47,37 @@ Generally, APIs are used by developers by calling endpoints with a specific HTTP The Kubernetes API is most of the time used differently: users create manifest files containing resources definitions in YAML format, and use the `kubectl` CLI to *apply* these manifests to the cluster. In this case, the most important information is the description of the structures used as parameters and responses (the Kubernetes Resources). -Because of this specificity, we realized that it would be difficult to adapt the `swagger-ui` interface to satisfy the users of the Kubernetes API. +Because of this specificity, we realized that it would be difficult to adapt the `swagger-ui` interface to satisfy the users of the Kubernetes API and this direction has been abandoned. ## Markdown pages -The second stage of the project has been to adapt the work I had done to create the k8sref.io website, to include it in the officiel documentation website. +The second stage of the project has been to adapt the work I had done to create the k8sref.io website, to include it in the official documentation website. The main changes have been to: - use go-templates to represent the output pages, so non-developers can adapt the generated pages without having to edit the generator code -- create a shortcode, to easily create links from inside the website to specific pages of the API reference +- create a new custom [shortcode](https://gohugo.io/content-management/shortcodes/), to easily create links from inside the website to specific pages of the API reference - improve the navigation between the sections of the API reference - add the code of the generator to the Kubernetes GitHub repository containing the different reference generators -All the discussions and work done can be found on [this Pull Request](https://github.com/kubernetes/website/pull/23294). +All the discussions and work done can be found in website [pull request #23294](https://github.com/kubernetes/website/pull/23294). -The Pull request to add the code of the generator to the Kubernetes GitHub repository is [this Pull Request](https://github.com/kubernetes-sigs/reference-docs/pull/179). +Adding the generator code to the Kubernetes project happened in [kubernetes-sigs/reference-docs#179](https://github.com/kubernetes-sigs/reference-docs/pull/179). -Here are the features of the API Reference included in the official documentation website: +Here are the features of the new API Reference to be included in the official documentation website: - 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 at the first level the associated resources, for example Pod, PodSpec, PodStatus, PodList -- each resource inlines its definitions (except when definitions are common to several resources, or are too complex to be displayed inline) +- 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) - required fields are indicated, and placed first - fields of a resource can be categorized and ordered, with the help of a [`fields.yaml` file](https://github.com/kubernetes-sigs/reference-docs/blob/master/gen-resourcesdocs/config/v1.20/fields.yaml) -- maps fields are indicated (ex pod.spec.nodeSelector is map[string]string, instead of object) using the value of `x-kubernetes-list-type` +- `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 +When the work is integrated, the API reference will be available at https://kubernetes.io/docs/reference/ + # Appreciation -I would like to thank my mentor [Zach Corleissen](https://github.com/zacharysarah) and the lead writers [Karen Bradshaw](https://github.com/kbhawkey), [Tim Bannister](https://github.com/sftim) and [Qiming Teng](https://github.com/tengqm) who supervised me during all the season. They all have been very encouraging and gave me tons of great advices. +I would like to thank my mentor [Zach Corleissen](https://github.com/zacharysarah) and the lead writers [Karen Bradshaw](https://github.com/kbhawkey), [Tim Bannister](https://github.com/sftim) and [Qiming Teng](https://github.com/tengqm) who supervised me during all the season. They all have been very encouraging and gave me tons of great advice. From 22e8714903976e55a20f417568b5ccfbd3c65a77 Mon Sep 17 00:00:00 2001 From: Philippe Martin Date: Fri, 4 Dec 2020 13:28:13 +0100 Subject: [PATCH 4/8] Add Celeste Horgan --- .../2020-12-04-gsod-2020-improving-api-reference-experience.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 f29242986f..97a89f0497 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 @@ -80,4 +80,4 @@ When the work is integrated, the API reference will be available at https://kube # Appreciation -I would like to thank my mentor [Zach Corleissen](https://github.com/zacharysarah) and the lead writers [Karen Bradshaw](https://github.com/kbhawkey), [Tim Bannister](https://github.com/sftim) and [Qiming Teng](https://github.com/tengqm) who supervised me during all the season. They all have been very encouraging and gave me tons of great advice. +I would like to thank my mentor [Zach Corleissen](https://github.com/zacharysarah) and the lead writers [Karen Bradshaw](https://github.com/kbhawkey), [Celeste Horgan](https://github.com/celestehorgan), [Tim Bannister](https://github.com/sftim) and [Qiming Teng](https://github.com/tengqm) who supervised me during all the season. They all have been very encouraging and gave me tons of great advice. From 551037ad30157e9b31f64d011cdc8b83bfe2d7e9 Mon Sep 17 00:00:00 2001 From: Philippe Martin Date: Fri, 4 Dec 2020 15:51:47 +0100 Subject: [PATCH 5/8] Season + headings --- ...gsod-2020-improving-api-reference-experience.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 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 97a89f0497..349f70abda 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,9 +7,9 @@ slug: gsod-2020-improving-api-reference-experience **Author**: [Philippe Martin](https://github.com/feloy) -# Introduction +## 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 during the autumn 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. @@ -17,7 +17,7 @@ I'm a software developer, with a great interest in documentation systems. At the 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. -# Background +## 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/). @@ -35,9 +35,9 @@ I decided later to add another output to this generator, to generate Markdown fi When the CNCF proposed a project for the Google Season of Docs to work on the API Reference, I applied, and the match occurred. -# The Project +## The Project -## swagger-ui +### swagger-ui The first idea of the CNCF members that proposed this project was to test the [`swagger-ui` tool](https://swagger.io/tools/swagger-ui/), to try and document the Kubernetes API Reference with this standard tool. @@ -49,7 +49,7 @@ The Kubernetes API is most of the time used differently: users create manifest f Because of this specificity, we realized that it would be difficult to adapt the `swagger-ui` interface to satisfy the users of the Kubernetes API and this direction has been abandoned. -## Markdown pages +### Markdown pages The second stage of the project has been to adapt the work I had done to create the k8sref.io website, to include it in the official documentation website. @@ -78,6 +78,6 @@ Here are the features of the new API Reference to be included in the official do When the work is integrated, the API reference will be available at https://kubernetes.io/docs/reference/ -# Appreciation +## Appreciation I would like to thank my mentor [Zach Corleissen](https://github.com/zacharysarah) and the lead writers [Karen Bradshaw](https://github.com/kbhawkey), [Celeste Horgan](https://github.com/celestehorgan), [Tim Bannister](https://github.com/sftim) and [Qiming Teng](https://github.com/tengqm) who supervised me during all the season. They all have been very encouraging and gave me tons of great advice. From 169712f33e4626139c25c1428a7bf38d406e3d40 Mon Sep 17 00:00:00 2001 From: Philippe Martin Date: Fri, 4 Dec 2020 19:04:50 +0100 Subject: [PATCH 6/8] future work + review --- ...2020-improving-api-reference-experience.md | 23 ++++++++++++------- 1 file changed, 15 insertions(+), 8 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 349f70abda..62d465a8ac 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 @@ -21,15 +21,15 @@ Shortly after, the DocBook language was adopted to write the Linux Documentation 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. +The existing API reference documentation is a large HTML file generated from the Kubernetes OpenAPI specification. -This API reference has some drawbacks: -- it is a single huge HTML page containing all the API reference -- its format is not adapted to mobile reading -- its design is not integrated with the kubernetes.io/docs website -- its content cannot be referenced by search engines +On my side, I wanted for some time to make the API Reference more accessible, by: +- building individual and autonomous pages for each Kubernetes resource +- adapting the format to mobile reading +- reusing the website's assets and theme to build, integrate, and display the reference pages +- allowing the search engines to reference the content of the pages -On my side, I wanted for some time to make the API Reference more accessible. Around one year ago, I started to work on the generator building the current unique HTML page, to add a DocBook output, so the API Reference could be generated first in DocBook format, and after that in PDF or other formats supported by DocBook processors. The first result has been some [Ebook files for the API Reference](https://github.com/feloy/kubernetes-resources-reference/releases) and an auto-edited paper book. +Around one year ago, I started to work on the generator building the current unique HTML page, to add a DocBook output, so the API Reference could be generated first in DocBook format, and after that in PDF or other formats supported by DocBook processors. The first result has been some [Ebook files for the API Reference](https://github.com/feloy/kubernetes-resources-reference/releases) and an auto-edited paper book. I decided later to add another output to this generator, to generate Markdown files and create [a website with the API Reference](https://web.archive.org/web/20201022201911/https://www.k8sref.io/docs/workloads/). @@ -68,7 +68,7 @@ Here are the features of the new API Reference to be included in the official do - 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) +- some widely used definitions, such as `ObjectMeta`, are documented in a specific page - required fields are indicated, and placed first - fields of a resource can be categorized and ordered, with the help of a [`fields.yaml` file](https://github.com/kubernetes-sigs/reference-docs/blob/master/gen-resourcesdocs/config/v1.20/fields.yaml) - `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` @@ -78,6 +78,13 @@ Here are the features of the new API Reference to be included in the official do When 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 + ## Appreciation I would like to thank my mentor [Zach Corleissen](https://github.com/zacharysarah) and the lead writers [Karen Bradshaw](https://github.com/kbhawkey), [Celeste Horgan](https://github.com/celestehorgan), [Tim Bannister](https://github.com/sftim) and [Qiming Teng](https://github.com/tengqm) who supervised me during all the season. They all have been very encouraging and gave me tons of great advice. From b12d3cb11461a5e1aa7d0611645ecd16e50e7949 Mon Sep 17 00:00:00 2001 From: Philippe Martin Date: Sat, 5 Dec 2020 03:20:42 +0100 Subject: [PATCH 7/8] 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 From 4b8e1d004744bf3af054d2b9adb0ec9422d1d8f7 Mon Sep 17 00:00:00 2001 From: Philippe Martin Date: Sat, 5 Dec 2020 03:26:58 +0100 Subject: [PATCH 8/8] fix period --- .../2020-12-04-gsod-2020-improving-api-reference-experience.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 eebcf32f69..76580cf475 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 @@ -84,7 +84,7 @@ The work is currently on hold pending the 1.20 release. When the release finishe There are points to improve, particularly: -- 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. - 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