Google Season of Docs Project Ideas

[katie-lamb]

Edit (4/12):

We are very excited to announce that Catalyst has been selected as a participating organization in Google Season of Docs for 2024! Please see our application information and Project Proposal page for information on technical writer applications and the work we're taking on.

Original Post

Catalyst Cooperative is applying for the Google Season of Docs.

Catalyst created the Public Utility Data Liberation (PUDL) project to bridge the gap between available and accessible U.S. energy data – publishing free and open-source energy data and collaborating with non-profits, scholars and local advocates working to decarbonize the U.S. We are looking for a technical writer who can improve the PUDL docs. By making our docs more digestible, we aim to expand the community of PUDL users and contributors. Writers should be comfortable with Python and ideally have some energy and power sector domain knowledge.

Google Season of Docs provides support for open-source projects to hire technical writers with grants ranging from $5,000 to $15,000. If you’re a technical writer who’s interested in one of our proposed projects, see the Technical Writer's Guide to learn more about applying. Then, contact us by sending an email to hello@catalyst.coop with a statement of interest. Let us know which project idea you're interested in and any relevant skillset/experience. If helpful, you can follow the technical writers statement of interest guide.

Project Proposals

1. Highlight Ten Most Useful Tables

Key need or problem: New users aren’t able to easily begin interacting with PUDL data – they need to wade through our entire data catalog and can’t easily find the tables that will answer their questions. A small subset of the many tables we publish are capable of addressing the majority of analysis questions and data needs. It’s unclear which of the tables in our catalog of data are most useful or good first places to look. This is a major deterrent from using PUDL and we lose users and potential contributors because of it.

Goal: In collaboration with PUDL staff, identify ten key tables to highlight for users. Write descriptions for these tables, as well as a landing page pointing new users to these tables based on the information they’re looking for (e.g., for information on generators, head to this page).

How would we measure success?:

• Increase in the number of new PUDL users
• Increase in the number of new PUDL contributors
• Increase in downloads of the ten tables
• Decrease in number of PUDL Office Hour attendances from people looking for data contained in the ten tables

What skills would a technical writer need to work on this project?:

• Familiarity with Github
• Familiarity with electricity infrastructure and key energy terminology
• Nice To Have: Familiarity with our test runner for the docs

2. Audit and update our existing fields and metadata

Key need or problem: Existing metadata for our data tables and fields contain typos, contain inconsistent amounts of information, lack clarity, and are often duplicative. Shorthands for units are inconsistent, and not always clearly communicated. An audit of fields would ensure that users are able to clearly understand what information is contained in a table when looking at PUDL’s metadata.

Goal:

• Update existing docs to clarify standardized expectations for field naming conventions (e.g., abbreviations)
• Review all existing fields and standardize field names and descriptions
• Review and update all table descriptions to conform to a common format
• Generate a list of potentially duplicative fields for PUDL staff to review.

How would we measure success?:

• Number of field descriptions updated
• Decrease in number of user questions about field or table descriptions
• Increase in downloads of existing tables

What skills would a technical writer need to work on this project?:

• Familiarity with key energy terminology (e.g., common units used to measure power)
• Clear and concise writing style

3. Reorganize our docs

Key need or problem: Currently PUDL documentation is spread out between the PUDL and PUDL Archiver Github repositories, PUDL’s ReadtheDocs and several pages on the Catalyst Cooperative website. Information may be duplicated, and is typically more up to date on the Github and ReadtheDocs than on the website. Clearly identifying what type of information should live in each place, and reducing the duplication of information would help ensure more regular updates. Additionally it’s difficult, even for long-time users, to understand what data is available in PUDL. We have the data dictionary page in the docs and the Datasette instance, but neither does a particularly good job of shepherding users to the data they want. PUDL needs a better, perhaps more nested, system of table/column documentation so users aren’t overwhelmed by the data and are actually using the right tables!

Goal:

• Audit existing documentation and identify the information that should be conveyed in each location
• Reorganize documentation to reduce duplication, and point to other information sources where necessary (e.g., add link to the ReadtheDocs on the PUDL website as appropriate).

How would we measure success?:

• There is no duplicate information in different places, we have clear guidelines for what documentation should live in the PUDL ReadTheDocs, Github, and website.
• Information on ReadTheDocs, Github, and website is up to date and is not contradictory
• Fewer PUDL Office Hours visits from new users asking about what tables to get started with or from users using interim data outputs instead of PUDL output data
• Increase in the number of PUDL users

What skills would a technical writer need to work on this project?:

• Clear and concise writing style and a strong sense of organization
• Familiarity with Github and ReadTheDocs
• Nice to have: familiarity with electricity infrastructure and key energy terminology
• Nice to have: familiarity with our test runner for the docs

4. Make table transformations/ETL journey more transparent

Key need or problem:

• We’ve gotten some questions from RMI and other users about how our tables relate to one another and what sort of transformations are applied to each dataset.
• New users don’t know whether to use the PUDL data, the raw data, or some interim data outputs.
• There are docs pages for the data transform modules, but they aren’t easy to find for someone with minimal technical expertise and they aren’t always that informative / really tell the story of what is happening to the tables.
• We have a different transform setup for the FERC and EIA data which makes this a bit complicated.
• Ideally we could do a better job of taking the doc strings from the transform steps and turning them into clear documentation without the need for ongoing maintenance every time something changes.

Goal:

• Users can explain what is happening to a table, how it gets transformed, and where to find different versions of the table.
• New and existing users feel less overwhelmed looking through the PUDL tables and documentation

How would we measure success?:

• Fewer PUDL Office Hour attendances from users who feel overwhelmed by searching through the data and don’t know whether to use raw, interim, or PUDL output tables.
• Increase in the number of PUDL users.
• Every transform step is explained within the docs and can be referenced for those who have questions. When adding new transform steps, there is a clear process for including it in the docs.
• Docstrings from transformation steps feed into and automatically update clear documentation on each transform step.

What skills would a technical writer need to work on this project?:

• Clear and concise writing style and a strong sense of organization
• Familiarity with Github and ReadTheDocs
• Awareness of an ETL process and a willingness to learn how tables change and differ at different parts of the PUDL data pipeline.
• Ability to find duplicate information in docs and organization skills to deduplicate it to a single location.
• Nice to have: Ability to edit docstrings in code so they are readable
• Nice to have: Ability to update docs automatically from docstrings
• Nice to have: familiarity with electricity infrastructure and key energy terminology
• Nice to have: familiarity with our test runner for the docs

[yashpandey06]

@katie-lamb
Greetings !! , seems like a perfect place for me !

[yashpandey06]

@katie-lamb Mailed a little Introduction about me , looking forward to some good contribution.

[katie-lamb]

Hi @yashpandey06 , thanks for your interest! Could you send your introduction to hello@catalyst.coop?

[yashpandey06]

@katie-lamb Sure !!

[yashpandey06]

@katie-lamb I sent you the introduction !! , could you just confirm?

[katie-lamb]

I don't see it, could you check your spelling of hello@catalyst.coop?

[tg-100]

Hi! I'm interested in the project

[yashpandey06]

@katie-lamb No issue , sending the another one !!

[yashpandey06]

@katie-lamb Sent the another one, also attached my Notion Portfolio

[DevangJagdale]

Hi @katie-lamb I was interested and was trying to join the slack group but it only allows certain email domains to join the group.

[yashpandey06]

@katie-lamb Hi there! After reviewing everything, I'm interested in tackling Project 2: Audit and update our existing fields and metadata. While working on PUDL in the docs ecosystem, I noticed inconsistencies, spelling mistakes, duplications, and areas that could use improvement for clarity. Project 2 aligns perfectly with my skills, as I have experience with SQL databases and have worked extensively with tables-based databases that PUDL is using to store data. Additionally, my technical background includes creating high-quality content using web technologies and databases, making me well-suited for this project's architecture. I encountered some environment setup challenges while trying to refactor PUDL docs yesterday, but I believe these can be resolved with guidance from the community. I've already begun working on the statement following the technical writer guide for GSOD 2024. Looking forward to your feedback and suggestions. Thanks!

[yashpandey06]

It would be so helpful if you please provide a way for transparent communication with the community as I am not able to join the slack for it 😕, I am facing some issues ,please look into this or may be tell me the correct way .

[katie-lamb]

Thanks all for your interest! For those of you that sent us an email, I just sent a response back. We are in the process of putting together our application for Season of Docs, and will begin reviewing the materials you've sent over once this application is submitted.

[Neilblaze]

Hi Katie 👋🏼,
Just confirming, hello@catalyst.coop is the email where I should forward my bio/intro, correct?

[yashpandey06]

Hey @katie-lamb ! , I've been reaching out to the community via the discussion forum, as well as commenting on pull requests and issues, but unfortunately, I haven't received any responses yet. Additionally, I've been unable to join the Slack space. I'd really appreciate it if you could help me find a way to engage with the PUDL community so that I can discuss any issues or doubts I have while contributing. Thanks!

[1e9abhi1e10]

@katie-lamb I sent you the introduction. Can you confirm it?

[yashpandey06]

@katie-lamb hey !! I will be sending you my GSOD proposal statement soon .

[yashpandey06]

@katie-lamb Congratulations !!!!! PUDL is selected for GSOD 2024 ....way to go !

[Abhijay007]

Hi @katie-lamb,

I am very interested in Project 3: Reorganize our docs and would like to take the next steps. I have thoroughly reviewed the project documents and am confident that I have the relevant skills and experience to accomplish the project. I would love to discuss the possibilities further.

As mentioned in previous comments on the thread, I understand that I need to send an introduction to hello@catalyst.coop. I will do that accordingly.

Thanks,

[pankaj-bind]

Hi @katie-lamb, I've a previous experience in technical content writing. I'm interested to contribute for this I've emailed my details on hello@catalyst.coop as mentioned in previous threads.
Thank you.

[Swpn0neel]

Hey,

I'm Swapnoneel Saha and am extremely interested in working on this project. I'm currently working as a Technical Writer at Tutorials Point, and have a lot of prior experience of writing technical content for my clients as part of my freelancing ventures. Also, this project aligns with my current expertise, and that's why I believe that I'll be a great fit for this project.

Here's my link to my LinkedIn profile
And, here are some of my writing samples:

1. https://swapnoneel.hashnode.dev/javascript-objects-vs-json
2. https://swapnoneel.hashnode.dev/inheritance-in-python
3. https://swapnoneel.hashnode.dev/devbytes-short-coding-news

Thank You,
Swapnoneel Saha
swapnoneelsaha111@gmail.com

[katie-lamb]

Hi all, we are very excited to announce that Catalyst has been selected as a participating organization in Google Season of Docs for 2024! Please see our application information and Project Proposal page for information on technical writer applications and the work we're taking on.

[Ayush9026]

Congratulations to PUDLP for GSoD 2024, and thanks to @katie-lamb for sharing the info!

[Kavisha4]

Hi @katie-lamb !! I am looking forward to contributing to CNCF as part of GSOD'24
I am a Software Engineer who is currently interning at Tesco.
I have worked with tools like Docker, Kubernetes, and Jenkins CI/CD.

I enjoy Technical Writing and User-Friendly documentation especially in Markdown.
My Medium Page: https://medium.com/@kvsha2002
I have also worked as a Technical Writer in Wiingy and curated multiple articles on SQL, C++, Javascript on Wordpress increased their reach using tactful SEO.

I am interested in Statement 3, will send across my proposal!

[Nancy9ice]

It's great to see that PUDL was accepted into the Google Season of Docs. Due to my interest in being one of the selected technical writers, I have some questions regarding the application process. In this project idea description, it was stated that we should send a project proposal. However, in the landing page, there were some other items as stated in the screenshot below. Are we also expected to send the items listed in the screenshot below alongside the project proposal? If yes, please could you clarify what the short writing sample would be? Is it expected to be anything at all? @katie-lamb @aesharpe

[aesharpe]

Hi @Nancy9ice-- This discussion was initially open-ended so we could generate ideas for project proposals. However, the SOD committee selected one of the proposals we sent them so we closed this thread. TLDR; you do not need to send us another project proposal.

If you'd like to apply, please send us an email with the 4 items you've listed above. The writing sample should be an excerpt from previous work that you think exemplifies your skills as a technical writer. It doesn't have to be long.