kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

future work + review

pull/25404/head
Philippe Martin 2020-12-04 19:04:50 +01:00
parent 551037ad30
commit 169712f33e
1 changed files with 15 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
content/en/blog/_posts/2020-12-04-gsod-2020-improving-api-reference-experience.md
View File

@ -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.