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.

Sign up for GitHub

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

Jump to bottom

[documentation update] Individual page audit #1220

Closed
16 tasks
chrisk-7777 opened this issue Aug 24, 2022 · 26 comments
Closed
16 tasks

[documentation update] Individual page audit #1220

chrisk-7777 opened this issue Aug 24, 2022 · 26 comments
Labels
documentation Improvements or additions to documentation

Comments

@chrisk-7777
Copy link
Collaborator

chrisk-7777 commented Aug 24, 2022 •
edited

Core conversation here: #1033

For each of the pages on the new documentation site, audit each page for clear, concise explanations, checking code snippets are correct, and conveys the correct information.

Blocked by #1215

Current list of pages, may change based on 1215 (above)

  • 3rd party libraries
  • auto generating selectors
  • event handler in pre react 18
  • flux inspired practice
  • immutable state and merging
  • Update immutable state and merging
  • introduction
  • maps and sets usage
  • persisting store data
  • practice with no store actions
  • recipes
  • testing
  • typescript
  • updating nested state object values
  • v4 migration
  • zustand v3 create context
@chrisk-7777 chrisk-7777 added the documentation Improvements or additions to documentation label Aug 24, 2022
@chrisk-7777 chrisk-7777 mentioned this issue Aug 25, 2022
Merged
1 task
@Exalted100
Copy link
Contributor

I'm working on subtask 'testing'.

@Exalted100
Copy link
Contributor

Do I create a new PR for each subtask or should I create one PR when I'm done with all subtasks?

@chrisk-7777
Copy link
Collaborator Author

Some of the pages are quite huge (like recipes).
Personally I would think smaller PR's are better - be it one or a few.

@dai-shi ultimately will be the one approving/merging them, so I'll leave it up to him (he's away for a few days, so there may be a delay over the weekend).

@Exalted100
Copy link
Contributor

I've worked on testing. Next, I'll work on autogenerating selectors, flux inspired practice, event handler in pre react 18, and immutable state and merging. I'll make a single PR for the changes I make to all five documents.

@Exalted100 Exalted100 mentioned this issue Aug 26, 2022
Merged
1 task
@Exalted100
Copy link
Contributor

Made a PR for the completed tasks here: #1231

Next, will be working on maps and sets usage, practice with no store actions, typescript, and updating nested state object values. Of course it will be in a separate PR.

@dai-shi
Copy link
Member

dai-shi commented Aug 28, 2022

Yes, I will merge PRs. But if @chrisk-7777 approves PRs, it helps moving forward, so please feel free to do so. Also, I may explicitly request for reviews.

@chrisk-7777
Copy link
Collaborator Author

Happy to review PRs. @Exalted100 I'll review later tonight 👍

@chrisk-7777
Copy link
Collaborator Author

#1231 Approved. Well written @Exalted100

@sewera
Copy link
Collaborator

sewera commented Dec 6, 2022

Hi @chrisk-7777 and @dai-shi!

I wanted to help with the documentation, but I wanted to ask you Chris to update the main comment if you find some time, so that it is clear which pages are left for audit.

I also can review some future doc PRs if some help is still necessary.

Cheers :)

@chrisk-7777
Copy link
Collaborator Author

@sewera can do. I've had to be away for the last few weeks, but aiming to get things back on track this week.
I'll ping you with an update soon

@sewera
Copy link
Collaborator

sewera commented Dec 6, 2022

Thanks a lot, looking forward to be a part of this <3

@sewera
Copy link
Collaborator

sewera commented Dec 13, 2022

Hi, just dropping in with a quick reminder :)

@chrisk-7777
Copy link
Collaborator Author

Thanks @sewera !

As a starting point, can you review the integration section, including the following links:

Key things to look for:

  • General spelling and grammar
  • Double checking code snippets work
  • Double checking all links on page work, both in Github and on the docs site
  • A little more subjective, but a consistent "voice" on the page. Does it read well, and is it consistent with other pages. I say subjective because we don't have a clear definition of voice yet, but if anything obvious jumps out, please update it (or check in here :) )

In terms of working locally with the docs, I have a comment here that may help get started: #1033 (reply in thread)

Feel free to split the above into 3 PR's or one, whatever is easiest for you.
Also feel free to "@" me anytime and I'll make sure to respond here

@sewera
Copy link
Collaborator

sewera commented Dec 13, 2022

Thanks for the reply, really appreciate your guide, I'll start right away!

sewera added a commit to sewera/zustand that referenced this issue Dec 13, 2022
@sewera
docs(pmndrs#1220): third-party libraries page revision
9301199 
- Make Zustand name always start from a capital letter,
- Unify list formatting and description style,
- Change minuses to em-dashes,
- Change 3rd to third.
@sewera sewera mentioned this issue Dec 13, 2022
Merged
1 task
@sewera
Copy link
Collaborator

sewera commented Dec 13, 2022

I managed to revise only the third-party libraries documentation page today. I opened a PR for it, so that you can start reviewing it right away @chrisk-7777 :)

sewera added a commit to sewera/zustand that referenced this issue Dec 14, 2022
@sewera
docs(pmndrs#1220): update links from 3rd-party to third-party
97d7dd9
sewera added a commit to sewera/zustand that referenced this issue Dec 14, 2022
@sewera
docs(pmndrs#1220): revise immer middleware page
87d666d 
- fix case in naming,
- check if the code snippets are up-to-date
sewera added a commit to sewera/zustand that referenced this issue Dec 14, 2022
@sewera
docs(pmndrs#1220): revise immer middleware page
ee4a500 
- fix case in naming,
- check if the code snippets are up-to-date
@sewera sewera mentioned this issue Dec 14, 2022
Merged
1 task
@sewera
Copy link
Collaborator

sewera commented Dec 14, 2022

Hi @chrisk-7777, I saw that you've already been notified, but I'll gather all the information here:

  • I've opened two PRs:
  • I've added a supplementary comment for the local docs dev setup;
  • Unfortunately, I won't be able to take up the third page (persisting-store-data.md/Persist middleware) for revision anytime soon. If there is no volunteer, I'll maybe find some time next week or later;
  • Obviously, I'll maintain my PRs and act on all the feedback I get there.

Thanks for your help, it's a pleasure to collaborate with you :)

dai-shi pushed a commit that referenced this issue Dec 15, 2022
@sewera
Revise the third-party libraries documentation page (#1478)
b1cea64 
* docs(#1220): third-party libraries page revision

- Make Zustand name always start from a capital letter,
- Unify list formatting and description style,
- Change minuses to em-dashes,
- Change 3rd to third.

* docs(#1220): update links from 3rd-party to third-party
dai-shi pushed a commit that referenced this issue Dec 21, 2022
@sewera
docs(#1220): revise immer middleware page (#1479)
4a99653 
- fix case in naming,
- check if the code snippets are up-to-date
sewera added a commit to sewera/zustand that referenced this issue Dec 29, 2022
@sewera
docs(pmndrs#1220): revise persisting-store-data page
28b8d9d 
- add cross-links
- add line breaks for easier Markdown reading
- unify Persist middleware spelling
- change fishes to bears, because the plural of fish is fish,
  and it would be less readable
- make sentences more concise
sewera added a commit to sewera/zustand that referenced this issue Dec 29, 2022
@sewera
docs(pmndrs#1220): make the sentences more concise
0cc2206
sewera added a commit to sewera/zustand that referenced this issue Dec 29, 2022
@sewera
docs(pmndrs#1220): unify formatting of methods
e310f19
@sewera sewera mentioned this issue Dec 29, 2022
Merged
1 task
@sewera
Copy link
Collaborator

sewera commented Dec 29, 2022

Hi @chrisk-7777 and @dai-shi!
I found some time to revise persisting-store-data.md,
as I mentioned in my previous comment,
and I've opened a PR for it — #1497.

Please review it when you are free.
I'll maintain my PR accordingly.

Happy to be a part of it, cheers! :)

dai-shi pushed a commit that referenced this issue Dec 30, 2022
@sewera
Revise Persisting store data doc page (#1497)
a8c98d6 
* docs(#1220): revise persisting-store-data page

- add cross-links
- add line breaks for easier Markdown reading
- unify Persist middleware spelling
- change fishes to bears, because the plural of fish is fish,
  and it would be less readable
- make sentences more concise

* docs(#1220): make the sentences more concise

* docs(#1220): unify formatting of methods
@sewera
Copy link
Collaborator

sewera commented Dec 30, 2022

Thank you guys for collaboration and PR reviews, it's very fun working with you!

sewera added a commit to sewera/zustand that referenced this issue Jan 5, 2023
@sewera
docs(pmndrs#1220): rephrase introduction to v4 migration
abca9bd
sewera added a commit to sewera/zustand that referenced this issue Jan 5, 2023
@sewera
docs(pmndrs#1220): rephrase create function migration
5bf4d25
sewera added a commit to sewera/zustand that referenced this issue Jan 5, 2023
@sewera
docs(pmndrs#1220): split migration for create function paragraph
f6c9e73
sewera added a commit to sewera/zustand that referenced this issue Jan 5, 2023
@sewera
docs(pmndrs#1220): rename page to migrating to v4
9047335
sewera added a commit to sewera/zustand that referenced this issue Jan 5, 2023
@sewera
docs(pmndrs#1220): restructure create function migration section
29e0017
sewera added a commit to sewera/zustand that referenced this issue Jan 5, 2023
@sewera
docs(pmndrs#1220): restructure StateCreator migration section
3ffaa73
sewera added a commit to sewera/zustand that referenced this issue Jan 5, 2023
@sewera
docs(pmndrs#1220): restructure PartialState migration section
7337901
sewera added a commit to sewera/zustand that referenced this issue Jan 5, 2023
@sewera
docs(pmndrs#1220): restructure and rephrase useStore function migration
bc9daef
sewera added a commit to sewera/zustand that referenced this issue Jan 5, 2023
@sewera
docs(pmndrs#1220): restructure all sections and reformat UseBoundStor…
cb51f7f 
…e and createContext
sewera added a commit to sewera/zustand that referenced this issue Jan 5, 2023
@sewera
docs(pmndrs#1220): fix applicable import for createContext
4824ea4
sewera added a commit to sewera/zustand that referenced this issue Jan 5, 2023
@sewera
docs(pmndrs#1220): rephrase persist middleware migration
50f9ca1
sewera added a commit to sewera/zustand that referenced this issue Jan 5, 2023
@sewera
docs(pmndrs#1220): rephrase redux middleware migration
9e7dd80
@sewera sewera mentioned this issue Jan 5, 2023
Merged
1 task
sewera added a commit to sewera/zustand that referenced this issue Jan 5, 2023
@sewera
docs(pmndrs#1220): simplify persist function migration
bc25353
@sewera
Copy link
Collaborator

sewera commented Jan 5, 2023

Hi @chrisk-7777 and @dai-shi!

The time has come for "v4 migrations" page.

The PR is #1507.

As usual, please review it when you are free.
I'll maintain my PR accordingly.

@chrisk-7777
Copy link
Collaborator Author

Thanks @sewera , really well written and explained.

I haven't really been keeping on top of the docs audit and rollout as much as I would've liked. Mainly due to work commitments.

If it's ok with Dai Shi, are you interested in becoming more of the "go to" person for the docs? I feel like you have a really good eye for detail and the overarching structure.

dai-shi pushed a commit that referenced this issue Jan 7, 2023
@sewera
Revise v4 migrations doc page (#1507)
820dbd3 
* docs(#1220): rephrase introduction to v4 migration

* docs(#1220): rephrase create function migration

* docs(#1220): split migration for create function paragraph

* docs(#1220): rename page to migrating to v4

* docs(#1220): restructure create function migration section

* docs(#1220): restructure StateCreator migration section

* docs(#1220): restructure PartialState migration section

* docs(#1220): restructure and rephrase useStore function migration

* docs(#1220): restructure all sections and reformat UseBoundStore and createContext

* docs(#1220): fix applicable import for createContext

* docs(#1220): rephrase persist middleware migration

* docs(#1220): rephrase redux middleware migration

* docs(#1220): simplify persist function migration
@sewera
Copy link
Collaborator

sewera commented Jan 7, 2023

Sure, @chrisk-7777. However, I'm only available on Wednesdays, and I can dedicate up to 2 hours weekly. If it's fine with you, it's also fine with me.

CC: @dai-shi

@dai-shi
Copy link
Member

dai-shi commented Jan 8, 2023

Sounds reasonable. Let's cooperate together.
@sewera Just sent an invitation.

@chrisk-7777 chrisk-7777 mentioned this issue Jan 17, 2023
Closed
1 task
@sewera sewera mentioned this issue Jan 19, 2023
Merged
1 task
@sewera
Copy link
Collaborator

sewera commented Feb 16, 2023

From what I've seen so far, the documentation on the Pmndrs website
is somewhat stable by now. If there are no actions left in this issue,
I'd say we should close it. What do you think @dai-shi and @chrisk-7777?

@chrisk-7777
Copy link
Collaborator Author

I feel like the sites docs are now in a good enough state that we can close this issue, and continue to iterate on the docs as needed.
Not to say the docs are complete, but I don't think it warrants an open ongoing issue anymore, rather smaller focused issues as they crop up

@sewera
Copy link
Collaborator

sewera commented Feb 16, 2023

That's exactly what I meant, I'm happy that we agree.
Amazing chapter in my open-source journey, so thank you all for that so far :)

@sewera sewera closed this as completed Feb 16, 2023
@dai-shi
Copy link
Member

dai-shi commented Feb 16, 2023

Thanks you all for your contributions!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
documentation Improvements or additions to documentation
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@dai-shi @sewera @chrisk-7777 @Exalted100