I am back from my very first Write The Docs (WTD) conference in Portland. I represented Cockroach Labs at the Writing Day. We set up our project for open source contributions and the response was amazing! And we were in good company – the other open source Writing Day projects included Kubernetes, Write The Docs, and Netlify. I also met up with Mike Lewis from GitLab and had a productive discussion about their open source contribution process. To summarize, I am pumped up about all things open source docs, and want to share all I learned with you!
Which brings me to an exciting announcement: I am teaming up with Information Developers Foundation to conduct a webinar about “Contributing docs to open source projects”. This is a topic I am passionate about because I have benefited immensely from working with open source projects. But my pet peeve is that while everyone agrees that contributing to open source is a great idea, nobody really talks about how to actually go about it. What is an open source project? How do you get started with one? What do you need to know to make meaningful contributions? What are the things to look out for, or things not to do? I intend to answer all these questions and also walk you through a few open source projects I personally like. So join me on May 19 at 8:30 PM IST to discuss how to contribute to open source projects. Here’s the registration link:
Also, feel free to send in any questions or topic suggestions you might have and I will try to answer them in the webinar:
In April, I had the privilege of sharing with you the day-in-the-life posts from four inspiring technical writers. To wrap up the series, I wanted to do something special. Which is why I made my very first day-in-my-life vlog! Here it is for your viewing pleasure:
Don’t forget to check out the day-in-the-life posts of our amazing guests:
Bart Leahy: Day in the life of a freelance technical writer (who previously worked at NASA and Disney)
Jason Tham: Life of a PhD student in Technical Communication
Swapnil Ogale: Day in the life of a contract technical writer in Australia
Larry Kunz: Day in the life of a technical writing veteran
Special announcement: There will be no post next week because I will be at the Write The Docs conference. However, I am planning to live-tweet the conference. Follow me on Twitter to keep up with the live updates!
Today’s post in this month’s series of guest posts is by Jason Tham, a graduate student currently pursuing a PhD in Technical Communication at University of Minnesota. I have studied Jason’s articles for the Research Methods in Tech Comm course for my Masters program and followed his academic career via social media. I am so excited you get to hear from him today. Here’s Jason’s post:
Collaboration is at the heart of technical communication, and I see at least two reasons to why that’s so: 1) technical communication materials are produced for human use and therefore always require human input; and 2) as cliche as it may sound, it remains true to me that no one knows everything, but everyone knows something––thus two or more heads are better than one when it comes to solving technical communication issues or tasks.
As a PhD student, my work in the past 4 years has been largely collaborative. Whether in practice or pedagogy, I have been acculturated to working with users, designers, researchers, and teachers. These interactions are often productive and rewarding; they help me create more effective documents, design and perform better studies, and deliver innovative instructions. In this guest post, I share some of my collaborative experiences in research, publishing, teaching, service, and professional practice.
Collaboration in research
After reviewing my CV, I realized more than half of my current projects are shared with other researchers in and out of my home department at my university. While I have worked in larger teams that ranged from four to eight researchers, my typical collaborations are in teams of two (myself and another researcher or scholar). Whether we are co-investigating a common problem or co-authoring a report, my experience with sharing a research project has been rewarding. I have always learned new research methods and strategies for communicating my findings. Furthermore, from a research standpoint, collaboration may boost the validity and reliability of a qualitative study if inter-rater reliability is utilized and achieved.
Collaboration in publishing
When publishing in technical communication journals (or any journal, I suppose), authors tend to work with journal editor(s) to identify the publication’s scope, standards, and other publishing specifications. I consider this interaction with journal editors and even responses to blind reviews as a kind of professional collaboration. Such collaboration ensures the quality of a publication––that authors produce scholarship that advance knowledge, reviewers provide feedback that enhance the scholarly merits of the refereed work, and editors ensure the integrity of the publication is preserved and supervise the production process.
I have also been blessed with the opportunities to co-edit some special issues of technical communication journals––most recently for the Journal of Business and Technical Communication and Computers and Composition––on special topics like “design thinking approaches for technical communication” and “immersive technologies and writing pedagogy.” In these co-editing experiences, I have collaborated with other academics to create calls for papers, review submissions, coordinate peer reviews, and work with authors and publishers. Special issue publications such as these tend to require a kind of collaborative dynamic that’s different from a regular journal issue as we had to draw resources from a select pool of experts and work within a specific publication timeline that complements the publisher’s workflow.
Collaboration in teaching
Based on my teaching experience, students find it more meaningful to work with problems that have tangible impact on their lives and those around them. As an instructor of technical communication, this means I need to work to bridge theory and practice in student learning. To achieve this goal, I have been collaborating with faculty members with other disciplinary expertise to co-design course modules and learning activities that benefit students in our classes. For instance, in the current (Spring 2018) semester, I am teaming up with a professor from mechanical engineering to create a learning unit for my business writing course where my students serve as press release writing consultants to graduate engineering students whom they are partnered with. This collaborative effort gives both my students and the graduate engineers in another course an opportunity to cross path and learn from each other.
Collaboration in service
As a member of the technical communication discipline, I am also called to provide services to the field that advance its visibility and wellbeing. In my opinion, these services are best done through collective effort and thus I have collaborated with other graduate students and scholars to co-organize events that led to the aforementioned goals. One example is the 21st Annual Great Plains Alliance for Computers and Writing Conference, where three active scholars in my department and I co-hosted in the Fall of 2017. Pulling together a regional conference isn’t a task that can be easily accomplished by an individual; by collaborating with colleagues and other graduate students, we were able to co-design a program that reflected the trends of the field and attracted presenters that had interesting topics to share.
Collaboration in professional practice
When not teaching or conducting research studies, I work as a leasing agent for a student housing provider. Collaboration is ingrained into my work routine; more often than not, I am working with other fellow agents to address leasing and marketing needs––we review our weekly leasing (sales) performance, discuss existing customer service issues, and come up with solutions to address these situations collaboratively. Also, part of my work is dedicated to maintaining a shared database of resident profiles and incoming prospects. Every leasing agent at my property plays a part in keeping shared notes and updating the database. Each year, it takes a team of six leasing agents, working very closely with a leasing manager, to fully lease our residence. While leasing and customer service may not be directly related to technical communication, they are communicative activities that require similar professional rigor.
Together, all these experiences help me grow as a technical communicator, whether through research, publishing, teaching, service, or professional practice. Indeed, as my academic advisor––Dr. Ann Hill Duin––wrote with her collaborator more than 25 years ago, collaboration in technical communication is a research continuum, rather than a static phenomenon or theory. The motivation and techniques for collaboration in technical settings keep shifting according to the context within which the collaboration occurs. My advice for rising technical communicators is to dip their toes in multiple collaborative contexts as part of their training so they may be hone their skills in collaborating with others.
Contact: Jason Tham, email@example.com
Since January 2018, I have been blogging thrice a week about pursuing a Masters in Technical Communication, being a Technical Writer, and becoming “more technical”. However, all the posts were based solely on my experience, thereby providing only my limited perspective about the field of technical communication. I wanted to know more about others’ experiences and provide diverse perspectives on the blog. So I invited the technical communicators that I have admired and learned from over the years, to share their experiences on this blog, and they accepted my invitation!
Hence in April, I am tuning down the frequency of my posts from thrice a week to once a week to focus the spotlight on our guest bloggers each week. Here’s the schedule:
April 4: Bart Leahy – Former technical writer at NASA and Disney, currently freelancing. In his post, Bart gives us a sneak peek into the day-in-the-life of a freelancer juggling multiple projects.
April 11: Jason Tham – A student pursuing a Ph.D. in Technical Communication. In his post, Jason gives us an insight into the collaborative projects in technical communication across academia, service, research, and publishing.
April 18: Swapnil Ogale – A technical writer in Australia, Swapnil shares a day in his life as a contract technical writer in Australia.
April 25: Larry Kunz – A veteran technical writer with 30 years of experience, he is a treasurehouse of knowledge!
I am so excited to share their knowledge and insights with you! Stay tuned and don’t forget to subscribe.
Came across and liked this web architecture basics video, so that’s our Tech Byte for today!
After last week’s post about Docs FixIt Day at Cockroach Labs, I received several requests asking me to suggest open source projects that people can contribute docs to. As far as I know, almost all open source projects accept docs contributions. The following list includes some open source projects I find interesting:
- Mermaid (Docs: https://github.com/mermaidjs/mermaidjs.github.io)
- Typo 3 Documentation
- OpenStack Docs
- Microsoft Docs
If you have any favorite docs-friendly open source projects, tell me about them in the comments. And don’t forget to subscribe!
Update 1: Suggestions from the community:
Update 2: Came across this article: Open Source Maintainers Owe You Nothing, which I thought was a mandatory read for anyone who wants to contribute to open source projects. It is important to remember that developers and maintainers of open source projects usually work on these projects on their own time and dime, and it is not their responsibility to help us understand how the project works. We need to put in our own efforts, read all available documentation, learn about the project on our own, before we ask for their help.
GitHub is a popular version control and collaboration. In my experience, learning GitHub can add tremendous value to your profile as a technical writer. GitHub enables you to contribute to open source projects and build your documentation profile. It also demonstrates your collaboration skills (working with developers and other team members), knowledge about version control, and overall technological literacy and comfort.
Getting started with GitHub is fairly easy. Follow the official guide to create your own repository!
And watch this video:
One of the life-changing books I have read in my professional life is Deep Work (affiliate link) by Dr. Cal Newport. As I discussed in the Day-In-The-Life blog post, I start my day with one-hour (2 Pomodoros) of Deep Work. And that has been the secret to my productivity and success as a technical writer.
Following are a couple of resources that summarize the book far better than I could have. Go through the resources, try out the technique, and drop me a line at firstname.lastname@example.org to let me know what you think of it. And don’t forget to subscribe!
Book summary: https://fourminutebooks.com/deep-work-summary/
Thе Pоmоdоrо Tесhniԛuе iѕ a time mаnаgеmеnt mеthоd developed bу Frаnсеѕсо Cirillо in thе late 1980s.Thе tесhniԛuе uѕеѕ a timеr to break dоwn wоrk into 25-minute intеrvаlѕ, ѕераrаtеd bу 5-minute breaks. These intеrvаlѕ are nаmеd Pоmоdоrоѕ, thе plural in Engliѕh оf the Itаliаn word Pomodoro (tоmаtо), after the tоmаtо-ѕhареd kitchen timеr thаt Cirillо uѕеd аѕ a university ѕtudеnt.
The Pomodoro tесhniԛuе helps you асhiеvе the following:
- Imрrоvе efficiency
- Kеер away from diѕtrасtiоns and fосuѕ оn thе task аt hand
- Imрrоvе timе-ѕеnѕе
- Eliminаtе ѕtrеѕѕ burnоutѕ
- Assist in аnаlуzing timе taken fоr tаѕkѕ
Hоw thе Pоmоdоrо Tесhniԛuе wоrkѕ
Thе Pоmоdоrо Technique rеgulаtеѕ when to diligеntlу fосuѕ оn a tаѕk аnd whеn you ѕhоuld take a brеаthеr.
This tесhniԛuе iѕ centered аrоund brеаking your timе down into роmоdоri (one Pomodoro iѕ еԛuаl tо 25 minutеѕ). You lоg a ѕресifiс tаѕk уоu are going tо work on and thеn ѕрrint уоur wау thrоugh thаt роmоdоrо. Aftеr 25 minutes of dеdiсаtеd wоrk, the timеr gоеѕ off аnd уоu tаkе a nice 5-minute brеаk frоm your wоrk.
Once your brеаk is over, уоu ѕtаrt аnоthеr 25 minutе long Pomodoro. This new роmоdоrо саn be dedicated tо thе ѕаmе tаѕk аѕ bеfоrе (if уоu did not complete it during thе previous роmоdоrо) оr a new оnе. Aftеr every 4 роmоdоri (рlurаl fоr роmоdоrо), уоu саn tаkе a lоngеr break, if уоu would like (ѕuсh аѕ fоr 15 minutеѕ).
While уоu’rе wоrking уоur way thrоugh a роmоdоrо, уоu can temporally interrupt it for uр to 45 seconds, if need bе. If thе interruption lаѕt fоr longer thаn thаt, уоur dеdiсаtеd fосuѕ оn thе mаin tаѕk iѕ viewed to bе lоѕt, аnd thuѕ thе Pomodoro iѕ rеѕеt (having tо ѕtаrt over at 25 minutеѕ) again.
Thе dеfаultѕ of 25 minutеѕ реr роmоdоrо, 5 minutеѕ реr rеgulаr breaks, 15 minutеѕ реr lоngеr break, and 45 ѕесоndѕ реr intеrruрtiоn seem to wоrk wеll for me аnd most people I knоw whо’vе triеd thiѕ hаndу tесhniԛuе оut. Hоwеvеr, that said, thоѕе arbitrary аllоtmеntѕ оf timе саn bе сhаngеd dереnding оn уоu реrѕоnаl hаbitѕ and ѕсhеdulе, ѕо аѕ lоng as уоu consistently ѕtiсk with thе аllоtmеntѕ thаt уоu’vе lаid оut. Fоr example, ѕоmе реорlе may prefer to wоrk “in the zоnе” for 50 minutеѕ, аnd then tаkе a 10 minutе break.
Why the Pomodoro Technique works
It is common experience that we can focus on a given task only for a short period of time before we get distracted (or seek out distractions). The Pomodoro technique helps to quantify and manage those focus periods. If you know you have to work for just 25-minutes, and then you can surf the web or check Facebook guilt-free, you will be more inclined to put in those 25 minutes of focused work. And you can get a lot done with 25 minutes of focus!
This technique has been a game-changer for me in terms of my productivity. As I discussed in the Day-In-The-Life blog post, I start my workday with at least 2 Pomodoros of focused work (which is almost one hour), and then I am free for the rest of the day to attend meetings, do some mundane tasks, socialize, or just goof off, because I have done the most important tasks for the day already.
The Pоmоdоrо Tесhniԛuе fоrсеѕ me to think in tеrmѕ of асtiоnѕ that nееdѕ tо bе tаkеn in order tо еffесtivеlу gеt things dоnе. It also imроѕеѕ thаt I рriоritizе аnd dесidе whiсh асtiоn I’m gоing to work оn. By hеlрing tо limit my аttеntiоn ѕраn tо a ѕinglе activity, thiѕ tесhniԛuе аidеѕ me in ѕtауing focused (instead of hopping between a handful оf diffеrеnt tаѕkѕ аnd/оr diѕtrасtiоnѕ).
Rеviѕiting my dаilу Pomodoro lоgѕ highlights whеrе I spend my timе аnd hоw рrоduсtivе I was thrоughоut a given timе period.
I now think of my tasks in terms of thе number оf роmоdоri thаt a givеn tаѕk might rеԛuirе. I diѕсоvеred that еvеn сhаllеnging tаѕkѕ саn оftеn bе tаkеn care оf in a handful of pomodori ѕеѕѕiоnѕ.
Try out the technique and let me know if it works for you. Drop me an email at email@example.com. And don’t forget to subscribe!
P.S: Here’s my favorite Pomodoro playlist: