operate-first / community-handbook Goto Github PK

Describe what is missing from the handbook

from this issue A clear and concise description.

If the documentation is for a task, have you discovered a solution?

Yes, No, I'm not sure, N/A

If you've discovered a solution, would you be willing to contribute it to the handbook?

Yes, No, If someone else helps write it, Other (specify), N/A

Additional Info

Please provide any additional details or information you'd like us to know.

Describe what is missing from the handbook

A style guide to inform/guide articles for the handbook

If the documentation is for a task, have you discovered a solution?

n/a

If you've discovered a solution, would you be willing to contribute it to the handbook?

n/a

https://www.operate-first.cloud/developer/
Graphic is in the new common slide @quaid put together

From the Contrib_X Docs WG:

We need to identify what docs are needed in the Operate First community.

We'll track progress on this here on the Community Handbook board https://github.com/orgs/operate-first/projects/20

ACTION: We need to determine how we're going to do this gap analysis and write that down.

OUTCOME NEEDED: List of doc needs that can be set up as individual issues to be worked on.

All community members are invited to add to the list of known doc needs by commenting here on this issue.

Make friendly for people brand new to the cloud native experience.

Make it possible (with a ToC) for those experienced in cloud native ways to skip ahead.

Include links to existing training.

Maybe put up "(coming soon)" links to the full array of training modules, like a roadmap?

The language of the templates should be a bit more general. The template should apply not only to documentation for specific tasks, but also for other documentation that is part of the handbook - such as updating the readme, or an article template, etc.

Specify the documentation

https://github.com/operate-first/common/blob/main/docs/add_gh_member_and_access.md#become-a-github-member

What problems have you discovered with it?

This document presumed an enormous amount of knowledge on the part of the reader and is only accessible to people who are already familiar with cloud native terminology, GitOps, CI/CD, DevOps, etc. etc.

Describe the solution you'd like

From the top, explain and quality every single bit of terminology, presuming the user does not have a familiarity with GitHub.

It's fine to point out to other GH basic rather than recreate, as long as it's all in a step-by-step process.

Additional context

We need to presume that new contributors are not familiar with a GitHub or GitOps paradigm.

Describe the task that is missing from the handbook

Handbook is missing a table of contents. We need to provide a table of contents so that anyone can look at the handbook and easily see what information they can find in it.

Have you discovered a solution to this task?

N/a

If you've discovered a solution, would you be willing to contribute it to the handbook?
Not a solution, but I can write it and add it to the handbook.

Describe what is missing from the handbook

We need a checklist for contributors to use when starting a new project, repository, etc. within the Op1st community.

If the documentation is for a task, have you discovered a solution?

Yes, we can fork from this bigger list, trim it down, and add any parts specific or unique to our community. (We can submit any useful changes back to the Open Source Way upstream.)

If you've discovered a solution, would you be willing to contribute it to the handbook?

Yes, but it will need review and changes by others to be accurate,

Additional Info

None

A kind of "cheat sheet" of all the commands, labels, and so forth anyone uses.

Describe what is missing from the handbook

from issue A clear and concise description.

If the documentation is for a task, have you discovered a solution?

Yes, No, I'm not sure, N/A

If you've discovered a solution, would you be willing to contribute it to the handbook?

Yes, No, If someone else helps write it, Other (specify), N/A

Additional Info

Please provide any additional details or information you'd like us to know.

Something is wrong with the issue templates - they have been created and merged into the repo via #1, but are not showing up when you go to create a new issue.

Coming soon!

Create a landing page for researchers, which we can link to from the Getting Started page.

This landing page should welcome and acknowledge the user experience of researchers, e.g. "We know from painful personal experience that GitHub and so forth are not so easy to use. This page is here to proxy some of the tasks for you, so you can focus on the work of your research."

An example of how this page can help:

1. The link for being added as a Member of the Operate First GitHub org is a Google Form; they fill it out and someone else does the github-config.yaml pull request to add them.
2. A set of quick links to most relevant documentation for them.
3. Finally, it explains how the "User and Contributor Handbook" works, and points them at the ToC for future needs.

Publish a generic article template that documentation can be structured around. Use discussion from #9 as a basis.

Describe what is missing from the handbook

A document to guide those looking to become contributors who may lack knowledge/experience contributing to open source projects. The guide will provide a few ideas of simpler, more accessible ways to contribute as well as point to helpful resources.

If you've discovered a solution, would you be willing to contribute it to the handbook?

I will work on creating this guide for the contributing section of the handbook.

Describe what is missing from the handbook

We need a page that explains how to use the core communication forum, which is a mailing list also accessible as a web forum.

If the documentation is for a task, have you discovered a solution?

Yes, the key is to not assume others have the experience of sending a mass email of information or requests to others. Include a few examples of what an email would look like.

If you've discovered a solution, would you be willing to contribute it to the handbook?

Yes, when I can.

Additional Info

This article may be useful beyond this project.

Proposal to make it more obvious who this is for.

Description:

• “Guide for how to be a user and contributor.”

Basically the page that you see here:
https://www.operate-first.cloud/community-handbook/

This is sourced from: https://github.com/operate-first/operate-first.github.io/blob/master/content/community-handbook/index.md

This is still mentioning the hitchhiker's guide, which is misleading.

Outcome:
Update community-handbook page to reflect the handbook, not hitchiker's guide.

Specify the documentation

https://github.com/operate-first/community-handbook#how-to-contribute

What problems have you discovered with it?

This is missing a pull request process and explanation of what is going on for new contributors.

Now that we're active in the Handbook, we need to tighten up the review process for additions and changes.

Describe the solution you'd like

1. Write up the pull request process
2. Make the editorial board reflect the workflow
3. Test and improve

Create an all-occasions page with curated or fresh content for new-to-GitHub

Work to clean-up and link in this document

From the Contrib_X Docs WG:

We need to list all the doc resources we currently have in the Operate First community.

We'll track progress on this here on the Community Handbook board https://github.com/orgs/operate-first/projects/20

ACTION: We are using this issue to collect that list along with the list of who they're targeting.

OUTCOME NEEDED: List of docs that we already have and information about who those docs are targeting.

All community members are invited to add to the list of known docs in the community by commenting here on this issue.

This is a curated list of content.

As we work on creating this list, we'll identify the gaps of what is missing.

We can have the OS-Climate user/contributor as the initial focus for who is getting started.

Describe what is missing from the handbook

from this issue A clear and concise description.

If the documentation is for a task, have you discovered a solution?

not yet

If you've discovered a solution, would you be willing to contribute it to the handbook?

Yes, If someone else helps write it

Additional Info

find out what ways there are, and what are the best, easiest to use