Hello friends! I recently gave a talk at the first annual PatternFly conference on some easy ways to take the writing you do for PatternFly from good to great. In it, I shared a few items that would comprise a short checklist that you can refer to as you write. Those items, and some others, are included here.
- Does this address Faith the front-end developer’s main questions and concerns?
- Does it give her what she needs to know to build a UI that impresses her team?
- Does it give her design guidance and info without lots of jargon?
- Is it written clear and completely enough that a beginner can be successful?
- Does this address Ron the reluctant front-end developer’s main questions and concerns?
- Does it include all the details he needs to plug-and-play?
- Is it written concisely without a lot of detail (backstory, implementation details, etc.) that won’t help him achieve his goals?
- Have I described how all the pieces work together, in case he wants to reverse-engineer it?
- Does this address Inga the interaction designer’s main questions and concerns?
- Have I described the use cases that this pattern addresses well?
- Have I described use cases that this pattern is NOT suited for? Did I include links to other patterns that might fit those other cases?
- Are the differences in the variations clear? Is it clear when to use one vs. another?
- Was this pattern tested with users? Is there a link to the findings?
- Have I addressed outstanding issues (i. e. incomplete information) and questions? Is there upcoming work on this pattern that I should mention?
- Is the writing style straightforward but not formal? Does it have a tone that sounds neutral and not like I’m telling you about it personally?
For blog articles:
- Can I break this into multiple posts?
- Is my call-to-action clear?
- Did someone who is like one of the personas read this? (For bonus points, have someone like each of the personas read it and give you feedback.)
- Did I run this through Grammarly to check spelling, punctuation, and grammar?
- Did I read it out loud?
- Does this sound like something I would say? In other words, is this written in my voice?
This list is not complete and should be considered a living document. If you have suggestions for additions, please let me know if the comments. If you use it for your writing, comment on how it worked for you.
Finally, if you attended my talk, I appreciate it! Let’s keep the conversation going — let me know your thoughts below about any writing you’ve done (or would like to do) for PatternFly.