What is a Peak Shift Improvement Proposal?

[johnsBeharry]

Title: PSIP Purpose & Guidelines
Author: @johnsBeharry
Status: Draft
Type: Process

Abstract

An Improvement Proposal is a specification of how an internal company process should be executed, including it's purpose and the steps required to do so. The Improvement Proposal is meant to introduce a new process, or make an improvement to an existing one.

Anyone participating in the company should be able to propose an improvement to our existing processes or specify new ones we should adopt.

Motivation

We have implemented some standard methods to solve reoccurring problems through the years but there is no documentation of them. This makes things difficult for us when we on-board new team mates among other things.

We should have a process to collaboratively make improvements to the company's operation processes.

Finally, our standard methods of operations should be documented and easy to reference so new team mates can have a easy way to get acquainted with "The Peak Shift Way".

Specification

PSIP Types

1. Process PSIP outlines the steps that are required to be followed in the operations of Peak Shift.
2. Informational PSIP describes a lose set of guidelines that serve as a recommendation more than a strict set of rules to follow.

Workflow

1. Idea
2. Submit PSIP
3. Review & Resolution
4. Maintenance

Formats

PSIPs should be written in markdown format. Once accepted, file naming should be PSIP-{issue_id}.

This issue would turn into PSIP-1.

Structure

1. Preamble -- Headers containing meta-data about the PSIP, a short descriptive title (limited to a maximum of 44 characters), the names, and optionally the contact info for each author, etc.

2. Abstract -- a short (~200 word) description.

3. Specification -- The technical details, or steps on how to apply / implement the proposed solution.

4. Motivation -- A clear justification on why the proposed solution is better than what is currently implemented, and the reasons the current standard is inadequate. PSIP submissions without sufficient motivation may be rejected outright.

5. Rationale -- The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work.
   The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion.

6. Reference List -- Add all resources that you have used are referenced directly to write the PSIP.
   In-Text Citation: Name of author, date
   Reference at the end: (Author Surname Year) References:Author Surname, Initial(s) Year (page created or revised), Title of page, Publisher (if applicable), Place of publication (if applicable), viewed Day Month Year, .

7. Bibliography -- Add any other materials (using the same format) that you have used for research on the specific PSIP but haven't directly referenced.

Rationale

Processed previously were difficult to explain or justify because most of them were verbal so referencing the exact details were difficult if not impossible.

Coming up with a structure for any document from scratch also gets in the way of writing down the details - by having a standardised structure for all processes to be written, authors can help readers focus on the solutions they're proposing.

Reference List

...

Bibliography

...

---

To better help visualise, things lets discuss what a proposal would look like. What are some processes/standards you think we could adopt?

Example:

Work Specifications should be written in Gherkin

• Gherkin language, is a "non-technical and human readable" way to define how a feature should work that allows both client and implementors to be clear of any ambiguity in work before it is started.

Objectives and Key Results of this discussion:

• Suggestions of at least 5 improvements we can implement.
• README.md with a clearly defined purpose for this repository.
• Contribution guidelines.
• Initial template for a PSIP.

This should be an open discussion - not one centralised around myself. I have no answers, that's why I'm calling on you all so we can collaborate and together form one.

A suggestion I have is bringing back the stand up meetings. At least one at the beginning of the week so that everyone is aware of what our objectives are. I feel it will be beneficial in having a stronger start in a week when there is a general plan of action or list of goals to achieve.
Another version could be that we have a stand up meeting at the end of the week to see what we have achieved, what still needs to be a achieved, and create and priortise goals for the next week.
What do you guys think?

One question I have too, what are we doing now in terms of project/task management? Are we still going to use JIRA? or is this one of the things we want to phase out of and adapt to the GitHub issues and discussions feature?

[selimira]

I absolutely agree with @esc758 about the standup meetings.
It will be important to make them structured and focused to ensure they are productive but essentially a 1 hour call when we for example discuss the following:

• review of what was achieved last week
• what is outstanding and will be it be done this week
• objectives for the next week
• free conversation. suggestions by anyone on new work, improvements, difficulties they are having etc.

[micey969]

Yep, definitely agree with @esc758 and @selimira on this one.
We also need to make sure we document our work properly and at all times and we clearly define the standards for what we are doing, so we don't lapse on it.
For instance, we have templates for the documents we will be using all the time, like the README. This is a template draft I did (https://github.com/peakshift/peakshift-docs/blob/master/PeakShift_Consulting/Templates/Readme.md).
I am proposing we implement a standard for our README documents and stick to it. Also, that each repo should have one.

[johnsBeharry]

@esc758, @micey969 nice suggestions, and @selimira good outline.

I came across this flow diagram, of the states that a proposal goes through for Ethereum - we can have a similar process too.

Additionally I found out that Python has a similar improvement proposal process that both Bitcoin and Ethereum are modeled after.

Please take a look at their PEPs listing, and their initial definition of their process in PEP-0001.