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] Information architecture redesigns and changes for Functions #15975

Merged
merged 10 commits into from
Jun 17, 2022

Conversation

momo-jun
Copy link
Contributor

@momo-jun momo-jun commented Jun 8, 2022

Motivation

As part (Phase0 & Phase1) of the actions to improve the doc set of Pulsar Functions, the motivation is to provide Pulsar users with a more user-centric, accurate, and comprehensive information experience.

Modifications

  1. Re-org topics (concept/task/reference) by applying topic-based authoring methodologies, which can contribute to revealing the complexity and granular pageview analytics.
  2. Clarify tasks for different user personas (admin&ops/dev).
  3. Introduce concepts about function instance, function worker, and window function in the Concepts topic
  4. Add a new Quickstart topic to help beginners to get started with Pulsar Functions.
  5. Refactor the content to make it easy to understand.
  6. Fix outdated information, errors, and typos in original docs.
  7. Streamline the visual styles of images and add several new illustrations.
  8. Update cross-ref links in more topics due to topic ID changes.
  9. Add a table to show the configurations that can be set via a YAML file --- implemented in PR: [improve][doc]single source of truth for functions CLI and add a table for yml configs #15389

To get a comprehensive view of the improved doc set (with a few screenshots for website preview) for Pulsar Functions, you can check out these Google docs:

The preview looks good. For more screenshots, see the above google docs.
image

Documentation

  • doc

@github-actions
Copy link

github-actions bot commented Jun 8, 2022

@momo-jun:Thanks for your contribution. For this PR, do we need to update docs?
(The PR template contains info about doc, which helps others know more about the changes. Can you provide doc-related info in this and future PR descriptions? Thanks)

@github-actions
Copy link

github-actions bot commented Jun 8, 2022

@momo-jun:Thanks for providing doc info!

@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 Jun 8, 2022
@Anonymitaet Anonymitaet removed the doc Your PR contains doc changes, no matter whether the changes are in markdown or code files. label Jun 13, 2022
@Anonymitaet Anonymitaet added doc Your PR contains doc changes, no matter whether the changes are in markdown or code files. and removed doc Your PR contains doc changes, no matter whether the changes are in markdown or code files. labels Jun 14, 2022
@github-actions
Copy link

@momo-jun Please provide a correct documentation label for your PR.
Instructions see Pulsar Documentation Label Guide.

@momo-jun
Copy link
Contributor Author

Hi @freeznet @nlu90, if you have reviewed the google docs, you can sign off the PR. Thank you.

@Anonymitaet Anonymitaet added doc Your PR contains doc changes, no matter whether the changes are in markdown or code files. and removed doc-label-missing labels Jun 17, 2022
@momo-jun momo-jun changed the title [improve][doc][do-not-merge] Information architecture redesigns and changes for Functions [improve][doc] Information architecture redesigns and changes for Functions Jun 17, 2022
@Anonymitaet
Copy link
Member

@momo-jun some images are PNG while others are SVG. Do you want to keep consistent and use SVG only?

We talked about this before, SVG is better than PNG:

  • Adaptive
    They adapt to the different sizes of the Chrome windows automatically.

  • Sharper and smaller
    SVG images are more crisp and clean, and they are in a smaller size.

  • Quality
    SVG is vector-based and can expand to any size without losing resolution

  • Accessibility
    SVG is XML-based, and can be read by both human readers and machines like search engines

@Anonymitaet Anonymitaet added this to the 2.11.0 milestone Jun 17, 2022
@momo-jun
Copy link
Contributor Author

@momo-jun some images are PNG while others are SVG. Do you want to keep consistent and use SVG only?

We talked about this before, SVG is better than PNG:

  • Adaptive
    They adapt to the different sizes of the Chrome windows automatically.
  • Sharper and smaller
    SVG images are more crisp and clean, and they are in a smaller size.
  • Quality
    SVG is vector-based and can expand to any size without losing resolution
  • Accessibility
    SVG is XML-based, and can be read by both human readers and machines like search engines

Yes, I plan to revamp these PNG files in Phase2. They are reused from existing materials and not aligned with our style.

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.

3 participants