Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit769a160

Browse files
authored
Merge pull request#228 from twangboy/add_docs_wg
Move docs-hub repo into community repo
2 parents6e46f95 +c3d9d12 commit769a160

31 files changed

+2295
-0
lines changed
Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
#CONTRIBUTORS AND SPONSORS
2+
3+
###Captain
4+
- Derek Ardolf, Salt project at VMware
5+
6+
###Salt Team Members
7+
- Derek Ardolf
8+
- Alyssa Rock
9+
- Ken Crowell
10+
- Sage Robins
11+
12+
###Community Team Members
13+
14+
This working group needs technical writers and developers to reach its goals.

‎working_groups/wg-Docs/README.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
#THIS REPO HAS BEEN MIGRATED AND ARCHIVED
2+
3+
New repository location:https://gitlab.com/saltstack/open/docs/docs-hub/
4+
5+
-----
6+
7+
>_This is the SaltStack Documentation Working Group repository. For other working groups,_
8+
>_checkout the[SaltStack Community](https://github.com/saltstack/community) repository._
9+
10+
#Documentation Working Group
11+
The purpose of the Documentation Working Group is to improve the overall quality of Salt documentation by:
12+
- Decreasing the time investment for new users to onboard
13+
- Scaling the docs for various user skill levels, beginning to advanced
14+
- Optimizing navigation for speed and relevance
15+
- Enhancing real world applicability by adding tutorials and clear use-case scenarios
16+
- Providing clear indicators of module maturity and stability in related documentation
17+
18+
##WORKING GROUP CONTRIBUTION GUIDELINES
19+
Guidelines for contributing to (and communicating with) this working group:
20+
- It is**not** required to be a member to assist the group's goal achievement
21+
- However, only members may advocate for solutions
22+
-**Action** is emphasized throughout the lifecycle and not simply planning and deliberation
23+
- Please complete task commitments
24+
- Do not over commit to task beyond your means
25+
- Ask for help and communicate to avoid developing in a vacuum
26+
- We encourage asking for help from other members**and** from the salt community, at large.
27+
- Put good faith effort into resolving issues with the current toolset before requesting to add/replace a tool.
28+
- No one is to add a tool without deliberation and consent.
29+
30+
##WORKING GROUP DETAILS AND TOOLS
31+
###Meeting details
32+
Meetings will take place every other Thursday at 2p.m. Mountain Time/3p.m. Central Time.
33+
Check the[Salt Community Calendar](https://outlook.office365.com/owa/calendar/105f69bacd4541baa849529aed37eb2d@vmware.com/434ec2155b2b4cce90144c87f0dd03d56626754050155294962/calendar.html) ([ICS](https://outlook.office365.com/owa/calendar/105f69bacd4541baa849529aed37eb2d@vmware.com/434ec2155b2b4cce90144c87f0dd03d56626754050155294962/calendar.ics)) for the Zoom link.
34+
35+
###Group Tools
36+
- Slack:**#documentation** channel at[Slack](https://saltstackcommunity.slack.com)
37+
- Additional tools are yet to be determined among the group captain and members
38+
39+
###Project task structure
40+
- Single day tasks (labeled[`SSD`](https://github.com/saltstack/docs-hub/labels/SSD%20task) solo single day task)
41+
- Page fix/adjustment/404 link error
42+
- Reducing a page’s complexity
43+
- Individual long term projects (labeled[`SLT`](https://github.com/saltstack/docs-hub/labels/SLT%20task) solo long term task)
44+
- How-to documentation
45+
- New page or section i.e. new feature
46+
- Consolidating pages
47+
- Multi-persons projects (labeled multiple tasks)
48+
- Code/tool migration
49+
- Creating new repositories/application for[docs.saltproject.io](https://docs.saltproject.io/)
50+
51+
##WHY JOIN?
52+
###Improving open source documentation has a big impact
53+
Good documentation helps orient newcomers, improves the project’s overall usability, and ensures that the community continues to grow. Even small contributions make a big difference.
54+
55+
###Users at any skill level can contribute
56+
If you are new to Salt and want to contribute as a community member, the Documentation Working Group is one of the best groups to join because it has a low barrier to entry for contribution. You will get more familiar with Salt and what it is like to contribute while working on a low-stress project appreciated by the entire community.
57+
If you are a seasoned user, your expertise is valuable because you have a better sense of what users expect when reading software documentation. All contributions are welcome!
58+
59+
###Documentation makes a difference
60+
In 2017, GitHub conducted the Open Source Survey, sampling 5,500 respondents. One key takeaway was “documentation is highly valued, but often overlooked.” The survey found outdated or confusing documentation to be a major problem, affecting 93% of respondents. Yet 60% of contributors rarely or never contribute to documentation. Consider giving back to the community by helping improve the docs.
Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
#Streaming on Twitch
2+
3+
How does streaming on the[SaltStack Twitch channel](https://www.twitch.tv/saltstackinc) work?
4+
5+
>_Only Salt maintainers and VMware employees currently stream through the Twitch channel._
6+
7+
##Table of Contents
8+
9+
-[Twitch Account](#twitch-account)
10+
-[Request SaltStackInc channel moderator/user permissions](#request-saltstackinc-channel-moderatoruser-permissions)
11+
-[OBS Studio](#obs-studio)
12+
-[Example Salt state on Pop!_OS](#example-salt-state-on-pop_os-and-ubuntu)
13+
-[Basic setup](#basic-setup)
14+
-[Quick reference](#quick-reference)
15+
-[Twitch chat and StreamElements chat moderation](#twitch-chat-and-streamelements-chat-moderation)
16+
17+
##Twitch Account
18+
19+
-[Create an Account with Twitch](https://help.twitch.tv/s/article/creating-an-account-with-twitch?language=en_US)
20+
- Take a look at[Twitch Creator Camp](https://www.twitch.tv/creatorcamp/en/) for a Twitch platform crash course
21+
- You're set to go, so now give[SaltStack Twitch channel](https://www.twitch.tv/saltstackinc) a follow!
22+
23+
##Request SaltStackInc channel moderator/user permissions
24+
25+
- Go to the SaltStack Twitch Chat (can do so from the main page of the channel without a stream happening)
26+
- Type in`/mods`
27+
- Reach out to the user(s) on the[SaltStack Slack Community](https://saltstackcommunity.herokuapp.com/)
28+
- Request SaltStackInc Twitch moderator and StreamElements permissions (at least Moderator or Super Moderator
29+
on StreamElements) too, which adds features like changing the stream title.
30+
31+
##OBS Studio
32+
33+
Install[OBS Studio](https://obsproject.com/), free software that can work on MacOS, Windows, and Linux.
34+
35+
###Example Salt state on Pop!_OS and Ubuntu
36+
37+
```
38+
{% set user_name = salt['pillar.get']('common:lookup:user') %}
39+
40+
'flatpak install com.obsproject.Studio -y --user':
41+
cmd.run:
42+
- creates: /home/{{ user_name }}/.local/share/flatpak/exports/share/applications/com.obsproject.Studio.desktop
43+
- runas: {{ user_name }}
44+
```
45+
46+
###Basic setup
47+
48+
An excellent video on using OBS Studio for streaming, scenes, sources, transitions, etc.
49+
-[OBS For Brand New Streamers](Creating Scenes, Adding Custom Widgets, and MORE)](https://www.youtube.com/watch?v=EuSUPpoi0Vs)
50+
51+
The following is covered:
52+
53+
- Overview
54+
- Setting Up Your First Scene
55+
- Adding Cool Widgets
56+
- Adding a Second Scene
57+
- Transitions
58+
- The Audio Mixer
59+
- The Settings
60+
- Switching Scenes w/ a Hotkey
61+
62+
####Quick reference
63+
64+
- The initial configuration wizard can be used for optimizing for streaming
65+
- Twitch can be selected, and the API streaming key should be entered
66+
-**OPTIONAL**: Can stream against personal channel for testing. OBS Studio provides a button that will go directly to the personal channel key location.
67+
- At a minimum, there needs to be one**Scene** with the following sources:
68+
-**Video Capture Device**: For selecting your webcam, if wanting to include your face on the stream
69+
-**Mic/Aux** (or**Audio Input Capture** using your mic): For viewers to hear your voice
70+
-**Screen Capture**: To share targeted windows, desktops, etc.
71+
72+
##Twitch chat and StreamElements chat moderation
73+
74+
-[Twitch Chat Commands](https://help.twitch.tv/s/article/chat-commands?language=en_US)
75+
-[StreamElements Chat Commands for SaltStackInc](https://streamelements.com/saltstackinc/commands)
76+
77+
Some example chat commands:
78+
79+
**Everyone**
80+
81+
```
82+
# Twitch
83+
/mods This command will display a list of all chat moderators for that specific channel.
84+
/w /w {USERNAME} {MESSAGE}: This command sends a private message to another user on Twitch.
85+
/block /block {USERNAME}, or click on a username and then on the Block button on the user badge that appears.
86+
/unblock /unblock {USERNAME}, or click on the Unignore button which replaces the Block button.
87+
88+
# StreamElements
89+
!uptime ${channel} has been streaming for 2 hours 20 mins
90+
!commands You can find a list of all Commands here https://StreamElements.com/${channel.alias}/commands
91+
```
92+
93+
**Moderators**
94+
95+
```
96+
# Twitch
97+
/timeout /timeout {USERNAME} [SECONDS], or clicking the clock symbol either directly in chat or on the user badge which appears when clicking on a username.
98+
/ban /ban {USERNAME}, or by clicking the Cancel symbol either directly in chat or on the user badge which appears when clicking on a username.
99+
/unban /unban {USERNAME}, or by clicking the Unban button which replaces the Ban button.
100+
101+
# StreamElements
102+
!settitle Update the stream title.
103+
```
Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
#2020-07-13 Meeting
2+
3+
##Attendees
4+
5+
* Derek Ardolf
6+
* Sage Robins
7+
* Cassandra Faris
8+
* Gareth Greenway
9+
* Alyssa Rock
10+
11+
##Meeting Details
12+
13+
###Future of Documentation Working Group
14+
15+
- Need to delegate out responsibilities based on interests
16+
- Should log who is doing what each quarter, and include in minutes in repo
17+
- Automated testing goals:
18+
- Linkchecks
19+
- Spelling
20+
- Potentially implement something like rstcheck?
21+
22+
###Process for New Working Group Meetings
23+
24+
- Post to the #Documentation / #Announcements channels leading up to working group
25+
- The notes/minutes need to be posted to the DocsHub repo
26+
- People who are watching the repository will be able to see updates in their feed
27+
28+
###Documentation Path Surveying?
29+
30+
- Discussed the potential of a survey: Welcome! What are you using Salt for?
31+
- Different reasons could provide feedback on how to better improve the docs based on:
32+
- SysAdmins / SysEngs
33+
- InfoSec / Incident Response
34+
- Other misc. paths
35+
- Google Analytics / Reports for Open Docs: Would love to take a look at how the docs are used
36+
- Need to reach out to SaltStack marketing team about analytics, and what we can learn
37+
38+
- Can we have a "formal" process for people to join the WG (subscription/newsletter)? This has been asked before, and we may want to implement something
39+
40+
##Clinic and Docs Jam
41+
42+
- Docs clinic in August: Tentative date of August 26th, 2020 (1hr)
43+
- Docs Jam in September, after Labor Day: Tentative date of September 9th, 2020
44+
- For docs clinic and docs jam process, should consult Alyssa on how 2019 workshop went
45+
46+
###Clinic ideas
47+
48+
- Towncrier: Making a good changelog entry
49+
- Docstrings: Making nicely documented functions
50+
51+
###Assignments or Action Items
52+
53+
- Derek: talk to Ryan in marketing about Google Analytics on Open Docs, if any, if not ask Bryce if Cloud Front data exists, agenda for next week's WG session will be to plan the Aug Clinic and Sep Doc Jam
54+
- Alyssa: take on communications, meeting minutes, agendas, reminders, and work with Cassandra on a Working Group Communication Plan, next WG session with Sage put together a Roles and Responsibilities outline, review, briefly
55+
- Sage: help Working Group with Project Management and Release Management as a role
56+
57+
###Decisions
58+
59+
- Alan will step away from the captain role for a while, he will still be involved. Derek will over this role, and responsibilities will divided among the entire group and rotated often so no one does a lot.
60+
- Meeting minutes will be kept in the docs-hub repo
61+
- Review the need to mirror issues from other repos into this repo - may not be needed with Derek heading up the captain role, does it provide value, if so, can it be automated?
Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
#2020-07-23 Meeting
2+
3+
##Attendees
4+
5+
* Derek Ardolf
6+
* Sage Robins
7+
* Cassandra Faris
8+
* Gareth Greenway
9+
* Alyssa Rock
10+
* Chad McMarrow
11+
* Ashley Newton
12+
* Wayne Werner
13+
14+
##Meeting Details
15+
16+
###Change of personnel and process
17+
18+
- Alan Cugler is stepping down as working group captain and Derek is taking over
19+
as captain going forward.
20+
- We’re going to take notes of working group meetings and we’ll post it on our
21+
docs hub. Alyssa will take this task for this cycle.
22+
23+
###First docs clinic
24+
25+
- These clinics will be modeled after the testing clinics and are designed to
26+
help community members overcome certain barriers to documentation contribution.
27+
- Our first one is tentatively August 19.
28+
- The first one will tentatively focus on getting yourself ready to contribute
29+
to the documentation (how to set up your GPG signing, learn how to find the
30+
core docs in the project vs. the module docs).
31+
- We had a discussion about how best to present and record the meeting.
32+
- Action items:
33+
- Cassandra has an action item to begin researching tips and tricks for a Best
34+
Practices Twitch guide.
35+
36+
###Docs jam planning
37+
38+
- Docs jam full day event: September 9.
39+
- We’re going to start by asking doc jam participants to take an open-ended
40+
survey about how they use salt modules and invite them to share use case
41+
scenarios. We might possibly use this data to add use case scenarios to the
42+
module documentation.
43+
- Participants will have 3 pathways to choose from for the docs jam:
44+
- Module case studies - Participants write brief blurbs about how they use
45+
certain modules in their environment.
46+
- Issue creation - Participants create issues based on problems in the
47+
documentation they’ve noticed. We’ll provide issue writing guidance.
48+
- Issue triage - Participants can work on documentation issues.
49+
- Logistics and action items
50+
- We’ll need 4 Zoom leaders at a given time. 1 in the main zoom room to help
51+
new participants get started and 1 for each pathway, which will be a
52+
separate breakout room.
53+
- Alyssa will create the first draft of the preparatory documentation
54+
- Sage will create an issues template and start by posting it to the docs-hub
55+
56+
###Next docs working group meeting: August 6
57+
58+
- We’ll identify a list of good first-time issues for new contributors.
59+
- We’ll also identify a list of modules we would love to get use-cases for.
60+
- We’ll continue reviewing logistics and action items for the first docs clinics and the docs jam.
Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
#2020-08-06 Meeting
2+
3+
##Attendees
4+
5+
* Derek Ardolf
6+
* Sage Robins
7+
* Cassandra Faris
8+
* Bryce Larson
9+
* Alyssa Rock
10+
* Chad McMarrow
11+
* Alan Cugler
12+
* Wayne Werner
13+
14+
##Meeting Details
15+
16+
###Change to upcoming docs clinic and docs jam dates
17+
18+
- The first docs clinic will be held September 30.
19+
- The full day documentation jam will be held October 7 from 8-5 MDT.
20+
21+
###First docs clinic planning
22+
23+
- These clinics will be modeled after the testing clinics and are designed to
24+
help community members overcome certain barriers to documentation contribution.
25+
- The first docs clinic will cover how to set up GPG signing and other necessary
26+
prerequisites for contributing to the docs.
27+
- Action items:
28+
- Cassandra and Wayne will work with Derek on the logistics of Twitch and
29+
YouTube for the docs clinics.
30+
- Derek will run a dry run of the first docs testing clinic with internal
31+
SaltStack employees to figure out how long the process might take.
32+
33+
###Docs jam planning
34+
35+
- Docs jam full day event: September 9.
36+
- Sage created a document of the Salt Modules Core to Salt for reference.
37+
- Alyssa created a rough draft for the docs jam participant guide and we
38+
discussed how to fill some of the logistical gaps in that document.
39+
- In our last working group meeting, we talked about the possibility of
40+
distributing a survey to get a sense of which modules are used most
41+
frequently. We've found that perhaps this won't be logistically possible and
42+
will instead create an issue template for submitting case studies (examples).
43+
- Action items:
44+
- Cassandra will investigate what swag packages we'll give to docs jam
45+
participants.
46+
- Sage will create the rough draft for the case study issue template.
47+
- Alyssa will continue fleshing out the rough draft for the docs jam
48+
participants guide. She'll refer to the port jam guide and incorporate good
49+
elements from that guide into this one.
50+
51+
###Miscellaneous documentation issues
52+
53+
- We checked in on the initiative to improve the contributor's guide.
54+
- We also checked in on the initiative to skip test suite for PRs that are
55+
docs-only changes.
56+
- We also talked about the initiative to convert the Salt docs to the Material
57+
theme and how to handle versioning.
58+
59+
###Next docs working group meeting: August 20
60+
61+
- We’ll identify a list of good first-time issues for new contributors.
62+
- We’ll also identify a list of modules we would love to get use-cases for.
63+
- We’ll continue reviewing logistics and action items for the first docs clinics
64+
and the docs jam.

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp