GSoD: Exploration phase for the technical writers

[malvikasharan]

Summary

• INCF is accepted as Google Seasons of Docs organisation, & The Turing Way is listed as one of the projects (see the proposal)

• May 11 to June 8 is an exploration phase for the professional technical writers who will bring a unique skill set to the project and collaborate independently.

• If a candidate contributes without completely understanding the role of technical writers and if their contributions demand more time from the reviewers than typical contributions in exchanging feedback, we will let the candidate know as soon as possible if their proposal can be supported by us or not.

Specific tasks suggested for the GSoD participants

We have narrowed down the following tasks and urge the GSoD participants to choose only one of them to work on during this exploration phase. These tasks will help the project team members in assessing the technical writing and communication skills of the interested candidates.

Technical contributions are always welcome, but pure tech contributions (e.g. fixing a broken link or refactoring code) will not be sufficient as a sample GSoD task - we need to learn about your writing, organisation, and collaboration skills as well.

• Add new content in code reviewing: https://the-turing-way.netlify.app/code_quality/code_quality.html
• Restructure the chapter on testing: https://the-turing-way.netlify.app/testing/testing.html
• Develop a section in Data license subchapter: https://the-turing-way.netlify.app/licensing/02/datalicenses.html

Work on the Remote Collaboration chapter that is under development in the PR #962 (issue #960):

• Format this subchapter on establishing protocols: https://deploy-preview-962--the-turing-way.netlify.app/remote_collaboration/protocols/protocols.html
• Develop a section in one of the following subchapters in Remote collaboration:
  • Managing resources: https://deploy-preview-962--the-turing-way.netlify.app/remote_collaboration/resources/resources.html
  • Tool choices: https://deploy-preview-962--the-turing-way.netlify.app/remote_collaboration/tools/tools.html
  • Leadership and management: https://deploy-preview-962--the-turing-way.netlify.app/remote_collaboration/management/management.html

NOTE: It is totally fine if multiple people want to work on the same topic, this is a collaborative project so we will actually look for a willingness to collaborate.

Further ideas can be discussed as a comment below or in an issue in this repo (see the next section for details.

Where can they start to learn about the project?

• Link to the project repository: https://github.com/alan-turing-institute/the-turing-way
• Project's README file and our Code of Conduct
• Contribution guidelines: https://github.com/alan-turing-institute/the-turing-way/blob/master/CONTRIBUTING.md
• Go through existing issues and Pull requests to explore where else you can contribute
• Open a new issue if you have any specific idea for contributions and/or proposals not listed above

What can The Turing Way offer during this period?

As an Open Source and contribution-driven project, we would like to invite interested technical writers to start engaging with the project as a contributor.

Here are the reasons why:

• We would like to encourage interested members to work openly and collaboratively in line with the community participation guidelines
• This will allow interested members to learn about the project while helping us see their enthusiasm and willingness to work on this project
• As technical writers they would be able to provide us examples of their writing skills through contributing to our project on GitHub
• This will also allow them to generate ideas for their proposal or consider if contributing to The Turing Way is the right fit for them
• If they end up getting selected, they will be able to keep on working with mentorship and guidance to further enhance their work within the project
• If they don't get selected or decide to not go ahead with the proposal, their contributions will still be counted and they will be listed as one of our community members.

For any further questions, please comment below!

Please Note

Contributing during GSoD exploration phase is meant to assess how well the candidates’ work fit to the requirement of a project.
We are looking for a technical writer who can support editorial work and bring in their unique skill set to help us improve the quality of our resources.
As a part of the exploration phase, we asked candidates to make a small self-contained contribution that can best demo their skills.
With that motivation in mind, we want interested candidates to be aware that we will try to let them know at least a week in advanced if they can be supported to write a proposal with The Turing Way.
It should not be assumed that contributing to the project will automatically secure you a position as a GSoD participant.

[KirstieJane]

This twitter thread has lots of great resources about technical writing - another possible idea is to grab one of the resources and review The Turing Way's processes to check that we're following best practice well!

Short chapters on how to write a paper, how to write an abstract (I love this example from Nature), how to write a bio (I know someone had a great template for this and I can't remember who now!) would also be great for the Communication series of chapters.

[growupboron]

This twitter thread has lots of great resources about technical writing - another possible idea is to grab one of the resources and review The Turing Way's processes to check that we're following best practice well!

Short chapters on how to write a paper, how to write an abstract (I love this example from Nature), how to write a bio (I know someone had a great template for this and I can't remember who now!) would also be great for the Communication series of chapters.

Aspiring GSoDer here, thanks for the great resource list. I also find, this compilation helpful : https://github.com/emptymalei/awesome-research

[malvikasharan]

I have updated the issue details to make sure that tasks are specific enough for the GSoD exploration phase.

Pinging @growupboron, @IIITM-Jay and @Yash-Varshney

[growupboron]

Thanks for the help.

[IIITM-Jay]

@malvikasharan I would love to go for Data License subchapter as dicussed with you.

[Yash-Varshney]

Thank you for a detailed description !

[Yash-Varshney]

I will start working on Restructure the chapter on testing.
Some of my initial ideas are -

• At first glance, the chapter looks tremendously huge. Generally, short articles attract more audience and are easy to read. So, I will divide the chapter into sub-sections first.

• Changing the python code written in between to a more-readable python-format.

any more suggestions or inputs from anyone, are highly appreciated !!
Thanks :)

[malvikasharan]

@Yash-Varshney That's a good start. Can you please open an Issue on that?

[Yash-Varshney]

@malvikasharan, as I have worked on the Restructuring the testing chapter and the review is still pending. So, can I work/collaborate on tool choices?

I have a very good experience in writing code for static analysis tools for various languages, and I am also one of the main contributors to a project for making meta-static analysis tools ( under INTEL org.). I could also write about it! :)

[malvikasharan]

Hey @Yash-Varshney, of course, you can contribute where you want. The tool choices section is for remote collaboration, some ideas for which are listed here and can be expanded in term of remote collaboration: #939.

If you think your content can fit in some other section as a case study or impact story, that's ok to go ahead and write that too (you can start a different issue for that).

[malvikasharan]

Questions in email by a GSoD candidate:

1. Have you already defined a table of contents (TOC) for the book? I understand that the data science community can contribute to the book at will. However, by defining a TOC the community might have a better understanding of the sections where they can contribute.

• The book is browsable in an online version with a navigation bar on the left side of the book that gives quick access to different chapters and subchapter: https://the-turing-way.netlify.app/. Each chapter has also an autogenerated TOC on the top right on the page.
  I don't think a separate TOC is needed, as it will be redundant.

2. Do you have someone from your team with the expertise to check and validate content? Since your main audience is researchers, this practice can leverage the accuracy and thus the usability of the book.

• This is an open source and collaboratively developed book project. The editing and reviewing are done collaboratively. The intention is to have the chapters evolve as per the need of our readers. Each chapter has at least two reviewers that often include a core team member for quality control. Each chapter is supported by references that are commonly stored in our bibliography section.

3. Do you want the book to address more theory than hands-on experience exercises? I noticed that from Chapter 10 the book has some ready to do code. This fascinated me because that would give the book more room for newbies. However, not all the sections of the book comply with that.

• Since the book is written by the community for the community, these are open for contribution. You can take them up if that's something you find interesting - or if you would like to help improve the chapter structure where we can make our authors think about adding hands-on exercises.

4. Although you have a Style Guide in your repository for new book entries, I am afraid that contributors do not stop by and read it in detail. This can lead to a lack of content consistency. I noticed that you suggest using prettier.io for checking the style and typos of your content. Does prettier.io allow you to integrate and check your own style guide rules? Or does it check its default rules? In this regard, would you be open to integrate other continuous integration tools that can facilitate the revision tasks for both the contributors and your team?

• The first step to contributing to The Turing Way is to read the contribution guideline, that defines the style guide as well. Our recommendations from the style guide are also integrated as GitHub actions (continuous integration), so whenever we have new content written by someone in a pull request (and even if they haven't read the style guide) - it undergoes a check for each rule. Additionally, reviewers of new content are asked to help our authors maintain consistencies. Often new contributors also take on the task of reviewing an already reviewed chapters and correct any missed error. This is a wonderful way for us to involve our members and let them have shared ownership of the work we are doing.

5. Have you already defined the tone and voice of the book? Do you want this to be ruled by the contributors? What are your thoughts?

• In our contribution guideline, we have defined the tone of how to develop content in this book. We use this book as a set of recommendations and allow "opinions" and the personal voice of the authors be reflected.

6. Do you have statistics about the book usage? Would you like to track them?

• Due to GDPR, we don't track personal information, however, we have our book on Zenodo that counts downloads and citation, and our contributors are directly added in the Contributors table.

7. What are your expectations for this project? I am afraid that a single writer might not have enough time (for a three month period) to achieve all your expectations including editing, contributing to new sections, and integrating new translations. In this regard, do you expect that more than a single writer can contribute to this project? If not, what are your priorities where I can contribute right away?

• Again, we have currently 150 contributors who collaboratively write, edit and support each other. It is never intended to be written by one person.
  Regarding a direct contribution for the GSoD candidates, we have listed a few possibilities in this issue. However, any other idea is welcome.

[CapTen101]

Hi @malvikasharan. Excited to start contributing to Turing Way project 😄
I'm onto the Add new content in code reviewing sub-task as my first contribution 😄

[agarwalmanvi]

Hi @malvikasharan , it's nice to be contributing here!
I'm working on the data licenses chapter for my first contribution. 🐣

[malvikasharan]

Hi GSoD folks, we have been quite busy this week, but we will let you know on Friday (12 June) via email whether or not we can support your proposal to GSoD. For any query, either reply here or contact me on Gitter if you need any further information.

[malvikasharan]

The GSoD application period is over hence I am closing this issue.