It’s 50 days until I turn 50!
So I thought I'd try to motivate myself to add more content to my blog by sharing a different docs tip every day.
Let's see if I can come up with one, small, helpful or interesting daily tidbit inspired by working on @astro docs.
Each one will be a blog post (in part, to remind myself that blog posts can be tiny, too!) and I'll update the main post below with a numbered list as I go.
Stay tuned for a tip later today!
Tip 23 - "is not was"
Write the docs you have, not how you got them.
Life is a journey, not a destination. Your docs readers, however, are not along for the ride.
Document your features, not how or why they came to be. "That would make a great blog post!" But, it doesn't make for great docs.
Read more about how this naturally shifts focus to *what your reader should do* (which is what they really came to docs for in the first place!): https://www.rainsberger.ca/blog/50-23-is-not-was/
@sarah11918 I am enjoying reading your series of tips! They are written in a way that will make it easy for me to repeat at work.
I have worked a lot with volunteers in the past and often reflect how much harder it is to work with them. You need to set standards but implement them with care or volunteers walk out. However, paid employees have an unspoken thing that ensures some degree of compliance - you will be out of a job if you don't pass minimum standards of compliance.
That is why I am so impressed with your work. You work on helping volunteers achieve standards in documentation. That is so hard. HT to you!
@perkinsy Aww... thank you so much for this lovely feedback!
This is special praise coming from you! I know your work in helping others feel comfortable contributing documentation makes you acutely aware of the difficulties wrangling tentative docs contributors.
I find it helps to give a reason behind my edits, the more specific, the better! Not, "This isn't good" but, "Hey, fun fact about reaching your reader..." I hope these tips can convey the same vibe. (And, will be ready for a break! 😅 )
Sarah Rainsberger
Yvonne Perkins