Skip to content

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

Merged
momo-jun merged 7 commits into
apache:masterfrom
momo-jun:authentication
Sep 20, 2022
Merged

[improve][doc] Improve the information architecture of the security chapter#17615
momo-jun merged 7 commits into
apache:masterfrom
momo-jun:authentication

Conversation

@momo-jun

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

Copy link
Copy Markdown
Contributor

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
Comment thread site2/docs/client-libraries-java.md Outdated
@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

@nodece nodece left a comment

Copy link
Copy Markdown
Member

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.

Comment thread site2/docs/security-jwt.md Outdated
Comment thread site2/docs/security-jwt.md Outdated
Comment thread site2/docs/security-jwt.md Outdated
Comment thread site2/docs/security-tls-transport.md Outdated
.build();
```

#### Supported pattern formats

Copy link
Copy Markdown
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
Copy Markdown
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
Copy Markdown
Contributor Author

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

@nodece nodece left a comment

Copy link
Copy Markdown
Member

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
Copy Markdown
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