Google Season of Docs: project proposal

natalieparellano commented 5 months ago

Project: Fill in missing docs content by adapting the CNB technical specification for buildpacks.io

About Cloud Native Buildpacks

Cloud Native Buildpacks (CNBs) transform your application source code into container images that can run on any cloud. With buildpacks, organizations can concentrate the knowledge of container build best practices within a specialized team, instead of having application developers across the organization individually maintain their own Dockerfiles. This makes it easier to know what is inside application images, enforce security and compliance requirements, and perform upgrades with minimal effort and intervention. The CNB project was initiated by Pivotal and Heroku in January 2018 and joined the Cloud Native Computing Foundation (CNCF) as an Apache-2.0 licensed project in October 2018. It is currently an incubating project within the CNCF.

The CNB project maintains a set of specifications and tooling (1, 2, 3) that make it possible to write buildpacks and orchestrate them together in a build system. Our community includes multiple (and sometimes overlapping) personas, including:

Application developers, who write source code that needs packaging into a container image,
Buildpack authors, who write buildpacks according to the Buildpack Interface Specification, and
Platform operators, who implement and maintain build systems that use buildpacks according to the Platform Interface Specification.

About the docs project

The CNB project maintains a specification that defines the contract that buildpacks, platforms, and a component called the lifecycle are expected to observe when builds are executed. Unfortunately, this specification is (by design) written in dry, technical language, and is intended for consumption by readers already familiar with CNB concepts and internal architecture. Additionally, the content is grouped together such that different personas (such as an application developer or platform operator) may struggle to find the content that is most relevant for them.

The project recently completed a reorganization of our documentation website to make it easier to determine where docs content should go. The content was divided first by persona (app developer, platform operator, buildpack author), and further separated by content type (tutorials, concepts, and how-to guides, according to the Divio docs model). During this process, we identified a significant amount of missing content - CNB features and concepts that are detailed in the technical specification, but are not covered on the website nor presented in a manner that is tailored to the personas for whom they are relevant.

Project scope

As part of this project, the technical writer will:

Spend some time with our existing documentation website to get to know buildpacks and the needs, concerns, and workflows of the different personas.
Become familiar with the CNB specification (both Buildpack and Platform) on GitHub to determine the relevant persona for each content section, and if it is currently documented on the website.
- For example, each entry in CNB terminology should have a page under “concepts” for the relevant persona; each entry in Data Format should have a “how-to” guide explaining when and how to create or use the file; and so on.
Where content is missing, create a placeholder page and corresponding GitHub issue to document what needs to be added (and where, linking to the placeholder page if possible).
Fill in missing content as needed and as time allows. The content should include:
- A plain language description of the concept or feature,
- Links to other relevant documentation or content,
- Diagrams (where appropriate) to facilitate understanding,
- Code snippets (where appropriate) to demonstrate example use.

Work that is out of scope for this project:

Updates to samples and tutorials. We expect the work to be mostly confined to adding “concepts” and “how-to” -style content.
Stylistic or cosmetic changes to existing content.
Further organizational changes beyond what has already been achieved via the recent reorganization.

We are currently inviting technical writers to apply for this project, and we estimate that this work will take six months to complete. The project will be supported by our Learning Team Lead @AidanDelaney, our Implementation Team Lead @natalieparellano, and our community manager @microwavables.

Measuring our success

In our most recent user survey, “better documentation” was the most highly requested planned feature by far, with 28/50 respondents (56%) indicating it is a priority for them. Free-form comments included sentiments such as “[the] documentation is very poor” and “I have had to look through the code to figure out what is happening”. A follow-up survey about our documentation after completion of the project would give some indication of how well we did.

Additionally, we will keep track of the number of Slack inquiries that we are able to address with a link to our existing documentation (vs a link to the spec). In the past 3 months, 12 of our community conversations in the #buildpacks channel have included links to buildpacks.io, whereas 6 have included links to the spec repo on GitHub. We aim to proportionally increase the number of conversations that are addressable with links to buildpacks.io.

Finally, we will track the number of GitHub issues (corresponding to placeholder pages where missing content has been identified) that are opened and closed throughout the period, with a tentative goal of over 45 issues (15 pieces of missing content added per persona).

Timeline

We estimate that this work will take six months to complete.

Dates	Tasks
May	Project familiarization (go through existing documentation to understand personas)
May-June	Review buildpack spec through the lens of a buildpack author to identify and fill in missing content on docs website
July-August	Review platform spec through the lens of a platform operator to identify and fill in missing content on docs website
September-October	With learnings from buildpack and platform specs, enumerate buildpacks features and the subset of concepts that are relevant to app developers; identify and fill in missing content on docs website
November	Finalize project, gather community feedback

Project budget

Budget item	Amount
Technical writer review existing content, identify missing content, and create new content for documentation website	8000.00
T-shirts (10, various sizes)	250.00

We are fortunate to have a number of contributors and maintainers who are willing to dedicate their time to this effort and/or are paid to work on the CNB project.

Additional information

Our existing contributors and maintainers actively contribute to the documentation website. We use the hugo framework which is relatively simple and intuitive and mostly involves working in markdown. There are a few stylistic and procedural conventions that we use (such as page titles and content summaries) that can be readily explained and documented.

Several of our contributors and maintainers, including project supporters @AidanDelaney and @natalieparellano, have participated in Google Summer of Code and/or LFX mentorships in the past, successfully guiding mentees to completion of their projects. From this we have learned the importance of setting clear expectations, having open lines of communication and regular check-ins, and exchanging feedback early and often. We are excited to bring these learnings to Google Season of Docs.

How do I get started?

If you are a technical writer interested in applying for this project, please:

We've created an application form to help us gather all the details from those that are interested in taking on the role of technical writer for the project. Please fill this out by 8:00am Pacific Time, Monday, April 22.
Reach out to us in the #buildpacks-learning-team channel on CNCF Slack with any questions
Spend some time getting to know buildpacks by reviewing our documentation website and the tutorials for each persona
- It is helpful to have some experience working with container technologies such as Docker, or systems that run container images (such as CI/CD)

UtkarshUmre commented 5 months ago

Hi @natalieparellano I'd like to work on the Buildpacks documentation for Google Season of Docs.

Srishti-j18 commented 5 months ago

Hi @natalieparellano and CNCF Buildpack team! I'm Srishti Jaiswal. I'm really eager to contribute to CNCF Buildpacks. Over the past month, I've been diving into build packs and Pack CLI, exploring sample and docs repositories, and even making some contributions. As documentation plays a crucial role, I'm keen to work as a technical writer for CNCF Buildpacks. Could you please guide me on how to apply for this?

radhathakare commented 5 months ago

Hi @natalieparellano I am eager to contribute to CNCF as I have been going through documentation also I have prior experience with the same stack also worked in docker, CI/CD pipeline, backend and frontend part earlier in GSOC last year. Could you plz guide me for Docs?

nishaaaaaant commented 5 months ago

Hi @natalieparellano I am interested in contributing to CNCF. I am a full-time Software engineer with 4+ years of experience with tools like Docker, Kubernetes, and Jenkins CI/CD. I am a seasoned technical writer skilled in technical writing, API documentation, and User-friendly documentation with experience in markdown and swagger documentation.

sharma-aarti commented 5 months ago

Hi @natalieparellano I am really interested in contributing to this project this summer as a technical writer. I have industry related experience working with docker and CI/CD pipelines as a Java developer. Linkedin

himanshuaggar commented 5 months ago

Hi @natalieparellano , I am Interested in contributing to the CNCF Buildpacks Documentation as a technical writer.

rajbhai99 commented 5 months ago

Hello @natalieparellano,

I am interested in contributing to the Cloud Native Buildpacks (CNB) project as a technical writer for Google Season of Docs (GSoD) 2024. I bring to the table prior experience in creating content for cybersecurity, Infosecurity, and cloud security domains. I have worked extensively on various compliance laws and regulations such as PCI DSS v4.0, GDPR, SOC2, ISO 27001, and more.

My familiarity with Governance, Risk, and Compliance (GRC), encryption, risk management, and APIs, positions me well to help make the documentation more compliant with regulations. I also possess a solid understanding of HTML, CSS, and JavaScript, which I believe will aid in writing and understanding code, thereby enhancing the quality of the documentation.

I am eager to apply my skills and experience to contribute to CNB as a technical writer. Could you please guide me on how to proceed with the application process?

Thank you.

Swpn0neel commented 5 months ago

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

pankaj-bind commented 5 months ago

Hi @natalieparellano , I've a previous experience in technical content writing. I've written 50+ article for GeeksFoGeeks organization. I am Interested in contributing to the CNCF Buildpacks Documentation as a technical writer. Here my articles profile link Aticles My resume Pankaj_Kumar_Bind_Resume.pdf My profile link LinkedIn

Thank you. contact: pankajbind30@gmail.com

IIITM-Jay commented 5 months ago

Hi @natalieparellano and the whole CNB team!, Hope you all are in good well being and doing great!

I am writing to express my interest in GSoD as a Technical Writer to work with the CNB Community.

I have worked with various open source communities and with diverse timezones. One of my successes that I would like to highlight here is my Outreachy internship wherein I have developed a pure OCaml Library to support TopoJSON. My name is recognized as the second author (Jay Dev Jha) of the library (first OfCourse the mentor), links can be visualized as follows:

Link1: https://github.com/geocaml/ocaml-topojson/blob/main/dune-project

Link2: https://github.com/geocaml/ocaml-topojson

I kindly request your esteemed attention to the following selection of my work samples, each accompanied by a succinct description.

Property Management System Documentation : The documentation, hosted on the "Read the Docs" platform, offers a comprehensive overview of the application, detailing its inner workings and providing a user-centric perspective.

Outreachy Presentation : I have done an Outreachy Internship with OCaml Community. My Mentor and the whole OCaml Community was proud of the work being done and the presentation that I gave. They appreciated the slides I have prepared after the completion of the internship. I had used Markdown and MDX for their documentation purposes.

Intermine Compendium : An encyclopedia is being designed for the InterMine Community covering system architecture and many more

TopoJSON OCaml Library : I have been entitled as the second author of the library (The first one is my mentor at the time of my internship)

Blog Post : Outreachy organizers liked and talked about one of my blog posts that I have done during my Outreachy internship

Hoping to hear from you soon.

My mail address to be contacted: jaydev.neuroscitech@gmail.com

Thanks and With Best Regards -Jay

microwavables commented 5 months ago

Hello @IIITM-Jay @pankaj-bind @nishaaaaaant @Swpn0neel @rajbhai99 @himanshuaggar @sharma-aarti @radhathakare @Srishti-j18 @UtkarshUmre !!

Thank you so much for your interest in helping out our project!! We've created an application form to help us gather all the details from those that are interested in taking on the role of technical writer for the project. Please fill this out by 8:00am Pacific Time, Monday, April 22.

Let us know in the #buildpacks-learning-team channel in the Cloud Native Computing Foundation Slack Workspace if you have any questions. Best of luck!

tarunsinghofficial commented 5 months ago

I'm interested in this project. How can we proceed further? Thanks

Ayush9026 commented 5 months ago

Thanks @microwavables for sharing application form.

Kavisha4 commented 5 months ago

Hi @natalieparellano !! 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.

bhartik021 commented 4 months ago

Hello, @natalieparellano!

I'm Bharti Kumari, currently pursuing a BTech degree in Electronics and Communication Engineering at Rajasthan Technical University (RTU). With over three years of hands-on experience in technical writing, I've played a pivotal role in producing top-tier content for esteemed organizations including GeeksforGeeks, Tutorials Point, Scaler, Pepper Content, and ProElevate. My expertise spans various types of documentation, ranging from API documentation and how-to guides to user manuals and product documentation. Additionally, I'm well-versed in CI/CD practices.

Basic Information

Name & Contact Information
Full name*	Bharti Kumari	Email address*	bhartik021@gmail.com
Slack username*	bhartik021	Discord*	bhartik021
Websites & URLs
GitHub*	github.com/bhartik021	Portfolio*	www.bhartikumari.in
Twitter*	twitter.com/bhartik021	LinkedIn*	linkedin.com/in/bhartik021
Article Portfolio*	Link	Medium*	medium.com/@bhartik021
Education
Institution*	Rajasthan Technical University	Degree*	Bachelors of Technology
Major*	ECE Communication	Graduation Year*	2024

shri3016 commented 4 months ago

Hi @natalieparellano, @AidanDelaney and @microwavables ,

Hope you are doing great:)Thank you for providing the application form. I had filled it out with my details and expressed my interest in contributing to the CNCF Buildpacks documentation project for Google Season of Docs 2024.

I'm Shriya Kamat Tarcar, a dynamic Technical Writer with a Bachelor's in Computer Science Engineering from Goa University. I bring a diverse background in technical writing, data science,software engineering and community engagement. Notable achievements include being selected as one of 15 global fellows for the Data Science for Social Good Fellowship at the University of Warwick,UK and one of 7 global interns for the Outreachy Internship under Wikimedia Foundation[An Open-Source Initiative]. My internship experiences, such as being a Developer Intern at Timble Law Associates,as an Outreachy Intern with the Wikimedia Foundation and as a Developer Champ at SAWO Labs have honed my ability to create impactful documentation. With experience in Docker, CI/CD pipelines, and a strong proficiency in technical documentation using tools like Markdown and Sphinx, I'm excited about the opportunity to contribute to CNCF Buildpacks.

Links to my profiles: 1] LINKEDIN 2] GITHUB 3] MEDIUM 4] MEDIAWIKI 6] DATA SCIENCE FOR SOCIAL GOOD FELLOWSHIP,UNIVERSITY OF WARWICK,UK 7] OUTREACHY WEBSITE 8] WIKIMEDIA FOUNDATION

Looking forward to the opportunity to collaborate with the CNB team!

Best regards, Shriya Kamat Tarcar shriyakt08@gmail.com

AryanParashar24 commented 4 months ago

Hello @IIITM-Jay @pankaj-bind @nishaaaaaant @Swpn0neel @rajbhai99 @himanshuaggar @sharma-aarti @radhathakare @Srishti-j18 @UtkarshUmre !!

Thank you so much for your interest in helping out our project!! We've created an application form to help us gather all the details from those that are interested in taking on the role of technical writer for the project. Please fill this out by 8:00am Pacific Time, Monday, April 22.

Let us know in the #buildpacks-learning-team channel in the Cloud Native Computing Foundation Slack Workspace if you have any questions. Best of luck!

Hey I know it's already 24th April but I really wants to contribute to this project and I would love to be a part of it so, if there is any way by which you can still gather my information and go through the profile for ones then it would be really helpful for me 😄

AryanParashar24 commented 4 months ago

Hi @natalieparellano, @AidanDelaney and @microwavables,

I know it's already 22 April, But if you could gather my information and get to view it for once then it would be really helpful. I really wants to contribute in building documentation for Cloud Native Buildpacks😊. Besides, here's my information:

Hey my name is Aryan Parashar, I'm the Developer Advocate at Lens IDE by Mirantis and Technical Writter at Hashnode & Medium. I am engaged in many Cloud Native Communities by building documentations through Articles, Project Documentations, Blogs and producing Video Content with a tutorial video for their project on YouTube, producing unit tests, Infrastructure solution consulting, Integration development & building secure environments with CNCF projects like Litmus Chaos, kNative, Open Telemetry, Gopher, Harbor, KubeVirt and many more. I am pursuing Bachelors of Engineering from MBM University, Jodhpur, Rajasthan, India. I have even won many Technical Writing contests with the recent one been organized by the Hashnode & WeMakeDevs with my blogs getting selected amongst the 410 submissions by the developers and solution architects for Cloud Native & Security domain. Here are my Socials to get connected:

Email address: aryanparashar24@gmail.com

I would love to work on the project for building documentations for Cloud Native Buildpacks to increase my experience and knowledge that I already hold about Cloud Native, if you could consider my profile and have a look at it or might allow me to fill the application form with even more details in it as required.

dubewarsagar commented 4 months ago

Hi @natalieparellano, @AidanDelaney and @microwavables,

I am Interested in contributing to the CNCF Buildpacks Documentation as a technical writer.

Thanks in advance.

rpsmaini commented 4 months ago

Hi there my name is Ravpreet Singh Maini. I am eager to work with such an opportunity. By contributing to this project I will expand my expertise and will acquire a foundational skill in the industry. Moreover I have an advantage of contribute to this project full time. For reference here is my linkedin profile: https://www.linkedin.com/in/ravpreet-singh-maini-0346b21b6 For further communication here is the email and contact number: 8871712525 rpsmaini@yahoo.com

microwavables commented 4 months ago

Hi @rpsmaini, @dubewarsagar, @AryanParashar24 and @bhartik021. Thank you for your interest in helping with our proposal. We received over 40 applicants through the application form that we linked within the proposal and in a comment above. The deadline to apply for the role was April 22 and we are not accepting any late submissions as we've already completed the interview process. We plan on making a final decision today from those that we interviewed. We still would love for you to contribute to the project and you can find more info on that here: https://buildpacks.io/community/#contributing

Thanks again!

natalieparellano commented 4 months ago

We want to sincerely thank everyone who applied for the technical writing position. It was an honor to get to know you all, and extremely inspiring to see the talent and passion within the community for technical writing and open source.

We are thrilled to announce that @hyounes4560 will be joining us for this Google Season of Docs. Hanan is an accomplished technical writer, and we are very excited to work with her. Welcome, Hanan!

kapelnick commented 4 months ago

Hello,

I am interested in contributing as a volunteer to your project, to gain experience in documenting open-source projects and GSoD in general.

Best regards, Nikos

natalieparellano commented 4 months ago

@kapelnick we'd love to have your help here. I'd encourage you to check out our docs issues to see if there are any you'd like to pick up. Or any general feedback you could offer as someone new to the project is always welcome.

I'm going to close this issue as we've completed the selection process, with thanks again to everyone for your interest.

jayzalani commented 4 months ago

Hello, I am highly motivated to contribute as a volunteer to your project, driven by my passion for open-source documentation and eagerness to gain hands-on experience in the Google Season of Docs program. This opportunity aligns perfectly with my goals of expanding my skills and making a meaningful impact within the open-source community.

Best regards, Jay

buildpacks / docs