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

Updating Tremor docs assessment formatting #70

Merged
merged 1 commit into from
Sep 8, 2021
Merged

Updating Tremor docs assessment formatting #70

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 13 additions & 12 deletions assessments/0004-tremor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ Each section rates content based on different [criteria](criteria.md).
| New user content | | ✅ | | | |
| Content maintainability | | ✅ | | | |
| Content creation processes | ✅ | | | | |

Scale:
- 1 = (Is not present or requires significant work)
- 3 = (Is present, but needs work)
Expand Down Expand Up @@ -67,9 +68,9 @@ Scale:
- The [scripts](https://github.com/tremor-rs/tremor-www-docs/tree/main/python_scripts) which generate certain pieces of documentation introduce fragility into the system: if the location of files, names of repos, etc. change then the documentation pipeline breaks. This also makes it hard for non-"technical" users to make changes to these pages, and to reorganize these pages if needed.
- The automation benefits might be worth it however.
- Your [release process](https://github.com/tremor-rs/tremor-www-docs/blob/main/RELEASE_PROCESS.md) is documented, which is great to see!
- Your site is only partially serachable, with sections not within /docs inaccessible by search.
- Your site is only partially searchable, with sections not within /docs inaccessible by search.

**Content creation processes:** There are no content creation processes documented and no CONTRIBUTING.md file for the main docs repository. Some things to think about:
- **Content creation processes:** There are no content creation processes documented and no CONTRIBUTING.md file for the main docs repository. Some things to think about:
Copy link
Collaborator

Choose a reason for hiding this comment

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

Just curious @nate-double-u: what changed in this line? Although they're not, they look the same in the online diff. Was it a change from a tab to a space or a hyphen to a dash, or some other hidden characters?

Copy link
Member Author

Choose a reason for hiding this comment

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

I've added a - at the beginning of the line for consistency.

Copy link
Member Author

Choose a reason for hiding this comment

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

(also, adding the - in some cases is what triggers the renderer to treat the next paragraph as a bulleted list. I thought this was the cleanest way to sort it -- we may want to revisit the template and use section H3 or H4 section headers instead in situations like this)

Copy link
Collaborator

Choose a reason for hiding this comment

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

(Oh, of course! Lol. I read the diff too quickly and took the diff - as a markdown list character! 🤷‍♂️
Right, it makes sense for consistency to include it in the list.

Copy link
Member Author

Choose a reason for hiding this comment

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

One - added at the beginning of the line is a bit of a sneaky diff...

- If I write documentation, who verifies that it's technically accurate?
- If I'm not a native English speaker, who can I ask for help with grammar and language review?
- If I'm a trained technical writer and want to rearrange, create new, or split existing topics, who do I tag in issues/on Slack for comment?
Expand Down Expand Up @@ -106,7 +107,6 @@ Scale:
- [Architecture Overview](https://docs.tremor.rs/overview/) (note: you could break out each of the "Model" sections into their own subpages)
- [History](https://docs.tremor.rs/history/), and I would consider titling this "Release log" or something similar
- [Understanding Data](https://www.tremor.rs/getting-started/codecs/)
-

- **Audit for colloquial/casual language, abbreviations, and other "basic" English:**
- This recommendation has less to do with casual language or abbreviations being _bad_, and more to do with the perception of professionalism for the project.
Expand All @@ -129,22 +129,23 @@ Scale:
| Beginner friendly issue backlog | | | | | ✅ |
| “New contributor” getting started content | | | | ✅ | |
| Project governance documentation | | | | | |

Scale:
- 1 = (Is not present or requires significant work)
- 3 = (Is present, but needs work)
- 5 = (Is executed extremely well or no improvement required)

**Comments**

**Communication methods documented:** [Contributing](https://docs.tremor.rs/Contributing/) documents these, but it would be useful to pull these up to the Community page
- **Communication methods documented:** [Contributing](https://docs.tremor.rs/Contributing/) documents these, but it would be useful to pull these up to the Community page

**Beginner friendly issue backlog:** You document your [GitHub best practices](https://docs.tremor.rs/Contributing/#pull-requests) and [issues for new users are tagged](https://github.com/tremor-rs/tremor-www-docs/issues?q=is%3Aissue+is%3Aclosed). Great work!
- **Beginner friendly issue backlog:** You document your [GitHub best practices](https://docs.tremor.rs/Contributing/#pull-requests) and [issues for new users are tagged](https://github.com/tremor-rs/tremor-www-docs/issues?q=is%3Aissue+is%3Aclosed). Great work!
- One thing to note is when tagging an issue [as a good first issue](https://github.com/tremor-rs/tremor-www-docs/issues/101), assume the reader knows nothing and must be hand-held through the entire process. [This issue](https://github.com/kubernetes/website/issues/28621) is a great example of the granularity needed by a first time contributor.

**New contributor getting started content:** The [Community](https://www.tremor.rs/community/) page exists but doesn't provide much guidance for new users. How do I get involved? When do community meetings happen? Where do I find the team on Discord or Slack?
- **New contributor getting started content:** The [Community](https://www.tremor.rs/community/) page exists but doesn't provide much guidance for new users. How do I get involved? When do community meetings happen? Where do I find the team on Discord or Slack?
- As mentioned above, [Development](https://docs.tremor.rs/development/) and [Governance](https://docs.tremor.rs/CodeOfConduct/) are targeted at contributor users and should be under the community section.

**Governance documentation:** Your [Project Governance](https://www.tremor.rs/governance/) is linked front and center, which I love! The only critique I have is that as a new user I am unlikely to click through to all of the links available. It would be lovely to distill these documents into something Tremor maintains at some point in the future.
- **Governance documentation:** Your [Project Governance](https://www.tremor.rs/governance/) is linked front and center, which I love! The only critique I have is that as a new user I am unlikely to click through to all of the links available. It would be lovely to distill these documents into something Tremor maintains at some point in the future.

**Recommendations**

Expand All @@ -164,31 +165,31 @@ Scale:
| Branding and design | | | | ✅ | |
| Case studies/social proof | ✅ | | | | |
| Maintenance planning | | ✅ | | | |

Scale:
- 1 = (Is not present or requires significant work)
- 3 = (Is present, but needs work)
- 5 = (Is executed extremely well or no improvement required)

**Comments**

**Branding and design:**
- **Branding and design:**
- On the whole, the Tremor docs site looks professional, if a little plain.
- Because of the way the site deploys (from different repositories via GitHub pages), navigation is disjointed: if you're in the RFCs, you don't have the full site's navigation available to you and clicking the logo takes you back to https://rfcs.tremor.rs, with similar behavior occurring in the docs. This is a bad user experience.
- Tremor could do a bit more selling on its homepage:
- What are the project's key features that make it different from other event processing systems?
- Are there any known use cases you can talk about or use the logos of?
- Have you given any talks on Tremor, or is there other (particularly video) content you can showcase about the project?

**Case studies/social proof**: None available.
- **Case studies/social proof**: None available.
- Case studies/talks/generally showing that other projects use Tremor is one of the most powerful ways to gain new users. People love real-world examples of a codebase in action.
- Because Tremor was developed by Wayfair, we suggest documenting Wayfair's use as a "use case" or case study, and then adding a section on the website which allows people to submit their own use cases!

**Maintenance planning:** In general, we recommend that projects keep their documentation all in one repository. Tremor's documentation currently deploys from https://github.com/tremor-rs/tremor-www-main, https://github.com/tremor-rs/tremor-rfcs, and https://github.com/tremor-rs/tremor-www-docs.
- **Maintenance planning:** In general, we recommend that projects keep their documentation all in one repository. Tremor's documentation currently deploys from https://github.com/tremor-rs/tremor-www-main, https://github.com/tremor-rs/tremor-rfcs, and https://github.com/tremor-rs/tremor-www-docs.
- It's confusing for contributors who don't know where to file issues, open pull requests, or whom to tag for reviews (and where).
- The easiest fix for this pain point is to deploy everything using and Hugo.
- In general, we prefer sites to deploy via Netlify.


**Recommendations**

- Develop a case study or other content around Wayfair's use of Tremor, to give users a tangible example of what they can do with the project.
Expand All @@ -212,7 +213,7 @@ Scale:
- Glossary
- FAQ (moved from top level navigation)

**Reorganize the top-level navigation of the site:**, once again, as mentioned previously:
**Reorganize the top-level navigation of the site:** once again, as mentioned previously:

- Getting Started
- Docs
Expand Down