As a newcomer to Fedora, I have been learning my way around the toolchain and @jwf encouraged me to make some concrete suggestions. I’m making these comments because I haven’t seen them anywhere else yet. Some of these are buried in a Pagure issue thread
We only have one chance to make a first impression
Have you ever looked into a tool or project and lost interest because you got stuck early on and couldn’t figure out where to go next? Or perhaps you were encouraged to make a suggestion, and then notice that there was no way to find out what would happen to it?
Put yourself in the other person’s position
It’s worth dong the exercise twice: first, imagine that you are the user and try to follow their flow through your project. Second, imagine that you are the same user and imagine what they don’t know about your constraints
For example, let’s suppose that you are maintaining a tool like, Pagure.
- You can ask yourself, What would I do if I wanted to make a contribution?
- You might start with the README and notice that there’s not much guidance on how to contribute issues or suggestions. OK, that might an obstacle.
- Next, consider that the user might not know what constraints or resources might be in place. For example, maybe there is only a process for internal team issues. Or perhaps there is a dedicated forum for developers… Oh, there is an IRC channel? Does it have an
.oncallperson? Office hours? What happens if the room is empty?
Let’s make it easy to write good READMEs
Tom Preston would say that a project should begin with the README
Even if you think Tom goes too far, I agree with @kevin that it would be good to have a standard About page So maybe CommOps can provide a template, or at least refer to a README generator
Have an public “API” to make it easy for outsiders to communicate with your team
I often hear “it’s hard to coordinate workflows because very team operates differently.” Yes, and most of the Web is built on four HTTP methods. External users don’t have to know how your teams scheduling, prioritization, issue tracking or performance metrics work. They just want to know what to do if they have a problem Who to contact if they need more information and when they might expect a change in status (not necessarily a resolution)
Typically, it should be enough to provide a little guidance like:
Looking to Contribute?
- To become familiar with the role of contributors, read
<mailing list | discourse | blog>
- To access the source code go to
Do you have suggestions?
- If you have a coment, you can email
<info at ...fpo>
- If you have a suggestion and you would like to follow its progress, please
<open an issue | email a mailbot>
- If you’re looking for a solution, consider
<FAQs | mail archive | Discourse | RTFM>
- If something used to work and now it doesn’t, then please
<IRC | email | SMS | etc>and you will receive a reply in XX hours. If you don’t get an update, then
<contact Blaise | Tweet "HELP" | call the ER>
Make it easy to measure engagement
In the ongoing discussions about how to measure engagement, notice a familiar problem where the data that is relevant to one objective is might be created as the by-product of some other team’s process.
For example, it might help the the commops or docs team to know:
- Weekly Active Users
- Broken links: (how many people try to get to a non-existent page? Where did they find the bad link?)
- Zero-reply threads (how many questions get no response? How old are they?)
- Feedback collectors (what comments come in from a particular page?)
- Page views (what pages are rarely read?)
That data is typically available from the
errors.log which the infra team keeps. The docs team could also benefit from knowing which Pagure issues might be related to content or user flow, but there’s no convention in place to tag issues in a particular way, so even the easy fixes might go unnoticed.