Internal documentation for working on Jekyll #5011
Conversation
Many, many thanks to Mike McQuaid for writing it: https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Maintainers-Avoiding-Burnout.md#3-prioritise-maintainers-over-users
@MikeMcQuaid Would love your feedback on this one. Writing from scratch here and I have the tendency to sound pretty formal. Thoughts?
|
Just completed three more docs: "Avoiding Burnout," which is basically a copy of Homebrew's; "Reviewing a Pull Request"; and "Becoming a Maintainer". I would love some feedback! |
|
|
||
| **This guide is for maintainers.** These special people have **write access** to one or more of Jekyll's repositories and help merge the contributions of others. You may find what is written here interesting, but it’s definitely not for everyone. | ||
|
|
||
| # 1. Use Homebrew |
There was a problem hiding this comment.
Probably not relevant to the Jekyll maintainers.
There was a problem hiding this comment.
Or rather... s/Homebrew/Jekyll, probably.
There was a problem hiding this comment.
Hehe, you see where I got this document from
|
This is so good! Are you still working on the triage one? |
|
I agree with @kytrinyx, this is a really solid addition to the documentation for the project. I'm still poking around in the existing documentation, so if I see anything of concern I will let you know. |
|
|
||
| You want to maintain Jekyll? Use it often. Do weird things with it. Do normal things with it. Does it work? Does it have any weaknesses? Is there a gap in the product that you think should be filled? | ||
|
|
||
| ## 1. Help Triage Issues |
@kytrinyx Yes! I am coming up a little short with some common things to look for but I'm sure it will evolve. I'll go triage some issues now for more ideas. |
@MikeMcQuaid I should clarify that further, yes. The idea of "reply quickly" is simply referring to an initial "we got your pr, here are our thoughts" reply. The idea of "resolve quickly" is definitely the idea that it should be merged or closed quickly. It's ideal for sure, though if review takes weeks, would the PR be better broken up into multiple PR's instead? |
|
@kytrinyx I wrote more in Triaging an Issue. What do you think? |
I think so but I also think some work is just complicated in terms of wider system effects (even if a just a few lines of code). May be worth clarifying here but I think it's also fine to leave as-is. |
| If the issue describes a feature request, ask: | ||
|
|
||
| 1. Is this a setting? [Settings are a crutch](http://ben.balter.com/2016/03/08/optimizing-for-power-users-and-edge-cases/#settings-are-a-crutch) for doing "the right thing". Settings usually point to a bad default or an edge case that could be solved easily with a plugin. Keep the :christmas_tree: of settings as small as possible so as not to reduce the usability of the product. We like the philosophy "decisions not options." | ||
| 2. Would at least 80% of users find it useful? If even a quarter of our users won't use it, it's very likely that the request doesn't fit our product's core goal. |
There was a problem hiding this comment.
I might be tempted to bump this number just because people tend to estimate in their own favour
There was a problem hiding this comment.
If you do keep the 80% figure, what methodology is used (or preferred) to identify that a percentage of the users would find the feature useful? I agree with @MikeMcQuaid that people tend to skew numbers in their favour, but if there is a set way to identify that 80% metric it makes it a little harder to fudge the numbers.
There was a problem hiding this comment.
what methodology is used (or preferred) to identify that a percentage of the users would find the feature useful
Hm... good point. This is all by gut measurement, really. I really stole the idea of the 80% thing from @benbalter. Ben, do you have a way of identifying this?
There was a problem hiding this comment.
Why not have features weighted by votes?
The problem here is exposure to these feature tickets.
There was a problem hiding this comment.
I think gut measurement is the best way to do this. Votes skew towards the type of users who vote on GitHub issue trackers which tend to be a different group to those of all those who use Jekyll. You could argue e.g. that all GitHub Pages users are Jekyll users but they might not even know what Jekyll is!
There was a problem hiding this comment.
You could argue e.g. that all GitHub Pages users are Jekyll users but they might not even know what Jekyll is!
Does GitHub Pages use Jekyll for something behind the scenes?
There was a problem hiding this comment.
@kytrinyx Yeh, basically every GitHub Pages project is implicitly a Jekyll project.
There was a problem hiding this comment.
Agree that direct voting will skew results towards power users. Logically, the new user experience would suffer because a potential user doesn't know to / want to vote until they're a user, and even then, have so little invested, that they're all but guaranteed to be underrepresented. See http://ben.balter.com/2016/03/08/optimizing-for-power-users-and-edge-cases/ for some additional context. Specifically:
The silent majority of users
Think about the type of user that's going to take the time to open an issue: they're either going to be power users that have already invested hours in your app and have grown the need for additional functionality that extends the core use case, or new and potential users with unique circumstances that you didn't originally intended to accommodate. In either case, opening an issue takes time, commitment to a cause, and specialized knowledge, and thus, through pure self selection, most issues are going to be opened by the extreme edges of your user base, not by the core of your users (or potential users, for that matter).
Instead of optimizing for the most vocal, feature requests should be evaluated through the lens of "what would benefit 80% of users?" — the silent majority, to borrow a phrase from politics. I suspect, for most projects, the exact opposite is sure, that 80% of feature requests come from just 20% of users (or as few as 1%). Combined with the fact that these requests often represent the "fun" problems, this 80/20 rule means that in many cases, absent your intervention, the majority of features implemented, will provide little or no benefit to the majority of users.
We can however, (in a subsequent pass) do a better job of identifying our core users and more narrowly defining our core use case, to help move things a bit from "gut" to "this doesn't fit our core use case" a bit more concretely and objectively.
|
The triage docs look really good. You might also get some good ideas from Steve Klabnik's blog post "Open Source Gardening" http://words.steveklabnik.com/how-to-be-an-open-source-gardener |
|
|
||
| # 1. Use Jekyll | ||
|
|
||
| Maintainers of Homebrew should be using it regularly. This is partly because you won't be a good maintainer unless you can put yourself in the shoes of our users but also because you may decide to stop using Jekyll and at that point you should also decide not to be a maintainer and find other things to work on. |
…automatic closure handling.
|
|
||
| ### Supported Platform | ||
|
|
||
| Is the author using a supported platform? We support the latest versions of macOS, and most common distributions of Linux. |
There was a problem hiding this comment.
@envygeeks what distributions of Linux do we want to support?
There was a problem hiding this comment.
Ubuntu, Debian, CentOS, Fedora, Arch. IMO.
|
@jekyllbot: merge +dev |
|
|
One thing I have not done well is write about how to maintain Jekyll. Historically, I have sort of been a "benevolent dictator" in dealing with issues and pull requests, basically making myself a blocker for moving the project forward at all. It's time to change that.
The purpose of this pull request is to empower all maintainers of Jekyll-owned projects to fulfill all duties, such that no one maintainer makes all the decisions or does the lion share of the work. It's a team effort.
Here is the beginning of some documentation for maintainers on @jekyll/core, @jekyll/plugin-core, or any team which grants write access to any repository on https://github.com/jekyll. It talks about handling issues, reviewing pull requests, and merging pull requests. Anyone who is looking for guidance when working on Jekyll should be able to refer to documentation on the subject at any time.
At the moment, I have:
There is still more work to be done, but please feel free to add thoughts here.
This idea borrows heavily from the Homebrew documentation, starting with Maintainers: Avoiding Burnout which @MikeMcQuaid shared with me today.
@kytrinyx & @beardofedu, this is my attempt at workflow-focused documentation rather than reference documentation. This is my first attempt, really, at writing this way so any feedback is welcome!