Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[improve][doc] Improve the information architecture of the security chapter #17615

Merged
merged 7 commits into from
Sep 20, 2022

Conversation

momo-jun
Copy link
Contributor

@momo-jun momo-jun commented Sep 13, 2022

Motivation

Improve the doc set of the Security chapter to provide Pulsar users with a more accurate, easy-to-read, and comprehensive information experience.

Note: This PR is a quick change to the overall IA of security topics. I will include more detailed IA changes and content changes for encryption and authentication in a couple of follow-up PRs, such as #17666.

Modifications

  1. Group encryption- and authentication-related topics in the sidebar (titles of some topics can be improved later).

image ----> image

  1. Move TLS encryption/authentication using Keystore sections to related parent topics, and remove Use TLS with KeyStore topic.
  2. Streamline the headings of authentication topics.
  3. Use language tabs to group code snippets throughout the security chapter.
  4. Remove the java code snippets from the java client page, and add links to individual authentication topics - fix [Doc] Authentication documentation mismatch / outdated #17561.
  5. Add code snippet for python clients to support basic auth [feat][python] Add basic authentication #17482.
  6. Add code snippet for go clients to support basic auth feat: add basic authentication pulsar-client-go#778.

Preview looks good. I've checked all the topics and here is one of the screenshots.
image

Documentation

  • doc

@momo-jun momo-jun self-assigned this Sep 13, 2022
@github-actions github-actions bot added the doc Your PR contains doc changes, no matter whether the changes are in markdown or code files. label Sep 14, 2022
Copy link
Member

@nodece nodece left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall looks good to me.

site2/docs/security-jwt.md Outdated Show resolved Hide resolved
site2/docs/security-jwt.md Outdated Show resolved Hide resolved
site2/docs/security-jwt.md Outdated Show resolved Hide resolved
site2/docs/security-tls-transport.md Outdated Show resolved Hide resolved
.build();
```

#### Supported pattern formats
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. ### instead of ####?

  2. Other headings are in the format of "Verb + xxx" while this heading is not.

Consider keeping consistent or turning this section into other content formats (like moving lines 97 - 100 to line 74)?

So that users know the relationship between the section Configure Athenz authentication in Pulsar clients and Supported pattern formats

(the info in Supported pattern format can be a part of Configure Athenz authentication in Pulsar clients )

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's copied and pasted here from another topic. I guess the intention was kind of to be a reference sub-topic so that's why #### was used (not shown in the hot links). Thanks for the reminder. It will be evaluated in a further review throughout the topic.

@momo-jun
Copy link
Contributor Author

@nodece thanks for the review. Your comments have been addressed.

Copy link
Member

@nodece nodece left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@momo-jun
Copy link
Contributor Author

@DaveDuggins This is the improvement I mentioned on this Wednesday. Feel free to take a look and comment.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Your PR contains doc changes, no matter whether the changes are in markdown or code files.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[Doc] Authentication documentation mismatch / outdated
3 participants