Sam suggests that we all (in our various stakeholder roles), start with our own proposals for how to do things in this GCC community. My (Sam’s) proposal:

7 Components To A HOWTO:

1. Review State: PROPOSED, WIP, RFC, ADOPTED

   1. Proposed: someone has suggested that this HOWTO be created
   2. WIP: this is work in progress, not ready for review, but available for co-authorship
   3. RFC: completed draft, requesting comments
   4. Adopted: After some reasonable period AFTER RFC without objection, the HOWTO will be ADOPTED.
      1. It is then available for practice
      2. and improvement.
      3. From “Adopted”, it can revert back to WIP if it needs revision
         (see different HOWTO)

2. Objective desired. What is the problem to be addressed?

   1. What are we trying to maintain? achieve? protect?

3. What are the preconditions? What needs to be true in order for this HOWTO to be applicable?

   1. What conditions describe the state of the community that can be addressed by this HOWTO?
   2. Each condition should be easily decidable / testable

4. What are the postconditions? How is the postcondition different from the initial state, before HOWTO application?

   1. After application of this HOWTO, what conditions describe the state of the community?
   2. Most helpful / best when stated as clearly testable conditions

5. Actual HOWTO

   1. The recommended procedure / process / guidelines / practices / heuristics… for how to do this, guided by #2, #3, #4

6. Related HOWTO’s (if any)

7. Update log (revisions)

   1. Date, Who, What – of change

So for THIS HOWTO:

1. Review State

   1. RFC (as of 20171224)

2. Objective desired:

   1. Community members would like to know how to write up a HOWTO
   2. In a common structure that is specific and understandable
   3. This HOWTO provides a way for the community to write up and share helpful guidelines, agreements, procedures, practices, protocols
   4. The corpus of HOWTOs allow fine-grain improvements / learning / revisions
   5. Not everything needs to be changed in order to evolve our practices one small step at a time

3. Precondition:

   1. There exists no clear HOWTO for how to create a HOWTO.
      1. If this precondition does not apply, then this HOWTO does not apply, and a new “HOWTO Create a HOWTO” is unnecessary.

4. Postcondition:

   1. There will exist this DRAFT HOWTO (for how to create a HOWTO) in RFC review state.
   2. This HOWTO will be specific and clear when guiding authors of new HOWTOs

5. Actual HOWTO Create a HOWTO

• Determine a need –

  • Did you want to
    • do something / take an action / make a decision
    • that is adopted by the community, and
    • know that it had implications for others in the community, and
    • not be clear how to do it?
  • Did you check to see if there was a related HOWTO already that could be adapted, revised, expanded, specialized… to cover this new something?
    • Recommended: Use HOWTO Find a HOWTO

• DRAFT it up

  • Use the template suggested below (enclosed / attached to this document)

  • Name it: HOWTO <action> – <MyID>

  • Initial Review State: PROPOSED (until draft is written)

  • Objective desired:

    • State the objective(s)

  • What are the preconditions?

    • State the preconditions

    • in a way that is easy to test / verify

  • What are the postconditions?

    • State the postconditions

    • in a way that is easy to test / verify

Propose in sufficient detail the HOWTO steps / instructions / guidance / procedure / etc you think works for the culture we are co-creating.

• Put it in a publicly reviewable place

  • Recommended:

    • Google Docs GCC HOWTOs Folder

  • Recommended: Add to HOWTO Index

    • https://docs.google.com/document/d/1g-EUMwuMviULhRg9QJOXNtIUPk6OnK-1ueIWYSXNWuo/edit?usp=sharing

  • Mark “Review State” as RFC

  • Announce it, and ask for review

    • Facebook GCC Group
    • Any groups that you feel would attract attention from GCC members
    • Set end / due date for reviews / comments / suggested revisions

  • Accommodate review feedback, ideally in public discussion thread (threaded by your announcement, with link to the HOWTO itself)

    • Do the best possible to accommodate review feedback
    • If feedback is not accommodated, provide good discussion & rationale (cite original objectives or group culture, values, etc)

• This HOWTO is now subject to a group adoption process

  • Not specifically addressed by this HOWTO

  • Recommended: Use HOWTO Adopt a HOWTO

TEMPLATE:

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

TEMPLATE for creating a new HOWTO (can be copied / pasted)

Name: HOWTO <<do something >> – <<Author>>

1. Review State: one of (PROPOSED, WIP, RFC, ADOPTED)
2. Objective desired.
   1. What is the problem to be addressed?
   2. What principles are to guide the HOWTO?
   3. What objective / outcomes desired?
3. What are the preconditions?
   1. What needs to be true in order for this HOWTO to be applicable?
   2. a condition that is easily testable / verifiable
4. What are the postconditions?
   1. How is the postcondition different from the initial state, before HOWTO application?
   2. a condition that is easily testable / verifiable
5. Actual HOWTO.
   1. Write up HOW to do this action
6. Related HOWTOs
7. Update Log
   1. When / Who / What (table form is suggested / recommended – see below)

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

Better template is here.

6. Related HOWTOs

• TBD, TBI

7. Update Log