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

Commit 0362d244 authored by Beth Hancock's avatar Beth Hancock 🌿
Browse files

Add new file - 2022 03 01 Meeting Agenda

parent 5ac1ca98
- [Meeting Information](https://opensource.ieee.org/community-advisory-group/documentation-curation/meetings/-/tree/main/)
# March 1, 2022
**Time:** 11:00 am - 12:00 pm Eastern
**Meeting link:**
https://communityag.leadingbit.com
**Meeting Recording:**
Meeting Recording failed.
## 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)**
*
*
*
## Meeting Notes
Previpous Meeting Notes:
* 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 possilbe 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 March 1, 2022 at 1:30pm.
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