IEEE.org     |     IEEE Xplore Digital Library     |     IEEE Standards     |     IEEE Spectrum     |     More Sites

Commit b641b620 authored by Beth Hancock's avatar Beth Hancock 🌿
Browse files

Add new file 2022 04 12 Notes

parent 790426db
- [Meeting Information](https://opensource.ieee.org/community-advisory-group/documentation-curation/meetings/-/tree/main/)
# April 12, 2022
**Time:** 11:00 am - 12:00 pm Eastern
**Meeting link:**
https://communityag.leadingbit.com
**Meeting Recording:**
This [meeting]() was recorded in BigBlueButton. BigBlueButton supports playback in Chrome and Firefox.
## Agenda
| What | Who | Time |
| ---- | ---- | ---- |
| Intros and agenda creation | All | 5 mins|
| How to add a new page to the handbook | All | ---- |
| Wrap Up and Next Meeting | Facilitator | 5 min |
## Action Items
**Current Meeting**
**Past Meeting**
## Attendees
**Please add your name and affiliation (work and volunteer)**
*
*
*
## New Handbook Page
### 2022 03 29 Meeting Notes
* Need to decide where to add this new page. https://opensource.ieee.org/community-handbook
* Added to the landing page: "This handbook is the central repository for how we operate the IEEE SA Open Community. Learn more about how we use the handbook and how to contribute to it: https://opensource.ieee.org/community-handbook/community-processes/handbook-guidelines/"
* During this meeting we updated https://opensource.ieee.org/community-handbook/community-processes/handbook-guidelines/-/blob/main/README.md
* Next meeting: Continue working on [Handbook guidelines](https://opensource.ieee.org/community-handbook/community-processes/handbook-guidelines/-/blob/main/README.md). Write general page guidelines and have an explicit call out about policies (e.g. keeping a changelog for a policy vs not for ).
* Nuritzi will be in Germany April 16 - May 29th. Would like to move the meeting during those dates to a more EMEA-friendly zone (8 am PST or earlier would be preferable).
### Old Notes for Reference
* We should create a "How to create a Handbook entry page" with a link to template.
* There is an IEEE SA Group that would like to start using the handbook to document various practices they've created. It would be helpful for us to create a general handbook page format.
* We think it would be helpful for pages to indicate who the audience is for that specific handbook page. For example, some may be for developers, others may be for marketing folk. In general, we want to encourage the community to give as much context as possible around what they are creating.
* This seems like it's more best practices around writing pages, not general format.
* It's more similar to policy docs. Some have revision histories, and in general there is more rigor to documenation for policy-minded organizations like IEEE SA Open. Some pages will need to have review dates as a function of the working group no longer being active, for example.
* Next time we meet: Consider writing the "How to add a new page to the handbook" page. Some information on this page may be helpful: https://about.gitlab.com/handbook/
### General Handbook Page Format
This is a space for us to work on various aspects of the handbook page format and template.
General Format Ideas:
- Table of Content
- "Codeowner" info (if possible) -- could be just words saying who contributors are
- Headers used throughout document
- Metadata to help with SEO (for people to be able to search and find info)
- Allow for people to use fontawesome icons
- Standard place in the handbook with information to share the context for that page.
Tooling magic: Hooking into the platform to automate as much as possible. These are things to keep in mind as we select the tool and shape it into what works best for our community.
* Linters -- spellchecking, simple punctuation, template elements
* Location -- is all it in one repository, or pulled in from multiple repositories?
* Editing in the browser: Full lifecycle from draft to publish
* Edit workflow automation
* Draft published view e.g. netlify.app
#### Questions
These are questions that we may want to answer in the handbook page we create about how to add a new handbook page entry.
* Audience - who/what role does the person you write this for have? What level of experience/detail?
* Purpose - why was this written?
* How complete is the handbook page? Draft,
* Should the handbook page be reviewed regularly? If so, how often and by who?
* How does one suggest changes/improvements to the handbook page?
* What is NOT in the purview of this handbook page?
#### How to add a page to the handbook?
Possibly create a "sample page"
* Using an issue: An issue template has all the basic fields that a handbook page needs:
* title
* author
* on this page
* table of contents
* maybe three sections with one subsection each.
The resulting issue would output the initial format of the document, since issue templates use MarkDown underneath and the issue field is MarkDown enabled. This generates the initial opening draft format, and the content can be pasted into a new MD file and merge request. The merge request is then tied back to the issue. The issue and the merge request can be tracked on an editorial project tracker board as cards moving through columns: drafting, developmental edit, draft edit, copyedit, ready to publish, published.
* The alternative (which may make more sense to many people's experience) is to work from a Template.MD, copy it and start a new merge request. That will be much more like editing code from the opening.
**EXAMPLE Layout:**
* handbook-page-toc title: Handbook
twitter_image:/images/tweets/handbook-gitlab.png
On this page
{:.no_toc .hidden-md .hidden-lg}
TOC {:toc .hidden-md .hidden-lg}
IntroductionSubHeading
## Next Meeting
Our next meeting is April 26, 2022 at noon Eastern US time.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment