Project Catalyst Recommendation for Core Documentation Standards

# Project Catalyst Recommendation for Core Documentation Standards `In this document, the term "Core Documents" will be used as a stand in for the Proposer and Challenge Team Guide, the Proposal Assessor Guide, the Veteran Proposal Assessor (vPA) Guide, and A Proposer's Guide to Assessment Flagging` ## 1 PURPOSE ### 1.1 Describe Problems with the Structure of Core Documents and Improvement Suggestions ### 1.2 Propose Solutions to Problems Identified * An example scheme for standardizing the Core Documents * An example scheme for standardizing document Improvement Suggestions ## 2 Problem Statement Rubric ### 2.1 Identify (What Problem Do We See?) The Project Catalyst Core Documents for Fund 9 were not uniform, organized, or consistent. Making improvement suggestions to the documents is challenging outside of something like Google Docs as the documents do not have a consistent structure, data scheme, or naming system. ### 2.2 Rank in Catalyst Context (Why is solving this problem important to the mission of Project Catalyst?) This is a very large current priority as many people are working to improve these documents. Fixing this can help to standardize the community's approach to editing these documents. ### 2.3 Solution Articulation (Describe the gap between the current state and the envisioned state?) Currently, the documents exist as standard Google Docs formatted to be viewed. The ideal state would be for these documents to exist as Markdown files on a GitHub repository (repo) where the sources would contain section heading numbers and line numbers so Improvement Suggestions could be tagged to a Section Heading a Line number in a simplified format. ### 2.4 Define Metrics (How might the value of solving this problem be quantified and/or measured?) Solving this problem should lead to a steep increase in the number of document Improvement Suggestions becoming actionable tasks or issues in DeWork or GitHub. respectively. ## 3 Recommended Changes for Core Document Standardization ### 3.1 Standardize Human Readable Document Names #### 3.1.1 Examples: * Proposer and Challenge Team Guide * Proposal Assessor Guide * Veteran Proposal Assessor Guide * Proposer Assessment Flagging Guide ### 3.2 Consider Encoding and the Core Document Names This is one suggestion for codifying the name of the Core Docs. This would be used for internal version control of the documents and standardizing improvement suggestion proposals. This system also suggests potential areas where key core documentation does not exist, but perhaps should, and where some documents may benefit from being broken into smaller, more targeted parts. #### 3.2.1 An Example Document Title Encoding Scheme ##### 3.2.1.1 CD (for core doc) ##### 3.2.1.2 Number Identifying Catalyst Phase [[source]](https://docs.catalystcontributors.org/project-catalyst/funding-process/funding-process) * 01 - Ideation * 02 - Proposal Submission * 03 - Proposal Refinement * 04 - Finalize Proposals * 05 - Assess Proposals * 06 - Review the Reviewers (Proposer Flagging and vPA) * 07 - Voter Registration * 08 - Voting * 09 - Vote Tallying * 10 - Rewarding * 11 - Reporting ##### 3.2.1.3 Code for Document Audience (who is this for?) * PR - Proposers * CT - Challenge Teams * PA - Proposal Assessors * VP - Veteran Proposal Assessors * VT - Voters * DR - dReps * GP - General Public ##### 3.2.1.4 Date Code for Estimated Fund Start date (Identifying the Fund) * 20211111 = Fund 7 * 20221102 = Fund 10 ##### 3.2.1.5 Example Document Titles * CD02PR20221102 = Proposer Guide for Fund 10 * CD05PA20221102 = Proposal Assessor Guide for Fund 10 #### 3.2.2 Sources: [Document Control Numbering Ideas (technicalwriterhq.com)](https://technicalwriterhq.com/documentation/document-control/document-control-numbering/) [Document Control (folderit.com) ](https://www.folderit.com/blog/document-numbering-system-document-control/) ### 3.3 Add a Version Control Tag to Human Readable Names * Fund (#) = locked document for the numbered fund * Live Edit = open for editing and suggesting `i.e. Proposal Assessor Guide - Fund 9` ### 3.4 Add a Numeric Section Heading to Each Document For example what I have done here should be a standard for each Core Doc so that Improvement Suggestions can be tagged to a specific section, subsection, and a specific line number in the markdown file. ## 4 Recommended Changes for Improvement Suggestions to Core Documents ### 4.1 Use a GitHub Repo to control changes to Docs #### 4.1.1 Why GitHub? GitHub contains several features that could dramatically improve Core Document Standardization ##### 4.1.1.1 Version Control Through features like forking, branches, and pull requests, the Core Documents can be edited by anyone in the community, and those changes can then be considered and agreed on by the community through pull requests. Then the changes for a specific Fund can be turned into a Release and Locked down with no further changes being allowed to that release, while the main documents remain open for community improvement suggestions. ##### 4.1.1.2 Markdown Language Markdown is a better style guide for standardized documents than the formatting in a word processor like Google Docs. ##### 4.1.1.3 Issues and Discussions GitHub has a builtin discussion platform and issue tracking which can easily turn into a pull request. This means there is already a way to turn Community Improvement Suggestions into actionable changes to the Core Documents. #### 4.1.2 A Potential GitHub Configuration Scheme * Main branch remains open for public pull request for live editing the documents * Create a GitHub Release for each Fund when the time comes that locks the documents and is not open for further changes changes * Utilize Issues to represent existing community Improvement Suggestions * Use the suggested document scheme proposed above to tie improvement suggestions to a specific location in a specific document * Implement the suggested changes in a unique branch or a user created fork, and then create a pull request bringing the suggested changes back into the Main branch. * Use the pull request code review feature to allow the community to give feedback and create a consensus mechanism for approving or rejecting the suggested document improvements. ### 4.2 Standardize the Format for Improvement Suggestions Every suggestion to improve the Core Documents should contain a standard set of information #### 4.2.1 Improvement Suggestion Requirements Every improvement suggestion must contain the following information to be considered valid. ##### 4.2.1.1 Document Name Either human readable name or preferably the encoded document id ##### 4.2.1.2 Section Heading and Line Number The exact section heading and line number that the improvement pertains to. If no one specific line is relevant, than the suggestion should be tied to the most relevant section. If no relevant section is found, then the suggestion should be attached to the closest relevant section. I assume that suggestions pertaining to changing the entire document are the least likely to be considered valid, while suggestions pertaining to single lines are most likely to be considered. ##### 4.2.1.3 The Current Text of the Relevant Section or Line As change suggestions will likely be considered apart from the document itself, the suggestion must contain the language of the relevant line or section that the suggestion seeks to change. ##### 4.2.1.4 The Suggested Replacement Text The improvement suggestion must contain the full replacement text of the section or line in question. #### 4.2.2 Improvement Suggestion Recommendation The following is not strictly required, but is highly recommended to gain community consensus for the Improvement Suggestion. ##### 4.2.2.1 The Problem Statement Rubric Answer each of the four following questions as simply and concisely as possible to share with the community why you believe your Improvement Suggestion ought to be adopted. * Identify: What problem do you see? * Rank in Catalyst Context: Why is solving this problem important to the mission of Project Catalyst? * Solution Articulation: Describe the gap between the current state and the envisioned state? * Define Metrics: How might the value of solving this problem be quantified and/or measured?