research

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 22, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package research reads and checks the research files of a newsletter project: verbatim voices of readers and writers, the peer newsletters of the niche, and evidence from standards and studies. The formats follow lfm's research files, so the same discipline applies: every item is verbatim, dated, retrievable and cited by ID.

Structure lives only in lines that start with a heading marker, a field marker or a table pipe. Quotes are blockquotes: every line starts with ">", so verbatim text may contain anything.

Index

Constants

View Source 
const (
	RuleFormat    = "research.format"
	RuleSubstance = "research.substance"
	RuleBalance   = "research.balance"
)

Rule IDs.

View Source 
const (
	Dir          = "research"
	VoicesFile   = "voices.md"
	PeersFile    = "peers.md"
	EvidenceFile = "evidence.md"
)

Files of a newsletter project's research directory.

View Source 
const (
	MinVoices    = 40
	MinPlatforms = 4
	MinPeers     = 8
)

Minimums for research started from zero.

Variables

View Source 
var (
	Authors       = []string{"reader", "writer", "adjacent", "expert", "brand"}
	Methods       = []string{"connector", "fetch", "browser", "user"}
	EvidenceKinds = []string{"standard", "study", "benchmark", "guide", "survey"}
	// PeerFields are the facts recorded for every peer newsletter, in order.
	PeerFields = []string{"Cadence", "Length", "Structure", "Subject", "Opening", "Voice", "Visual", "Links", "Signup", "Takeaway"}
	// Dimensions are the aspects evidence can apply to.
	Dimensions = []string{"deliverability", "consent", "signup", "welcome", "frequency", "timing", "length", "subject", "preheader",
		"layout", "accessibility", "images", "links", "tone", "structure", "personalization", "engagement", "growth", "retention",
		"unsubscribe", "hygiene", "measurement", "legal", "plaintext", "darkmode", "mobile"}
)

Fixed vocabularies.

Functions

func Blockquote 

func Blockquote(text string) string

Blockquote formats verbatim text as quote lines that parse back to the same text.

func ParseEvidence 

func ParseEvidence(text string) (Evidences, []Problem)

ParseEvidence reads evidence.md.

func ParsePeers 

func ParsePeers(text string) (Peers, []Problem)

ParsePeers reads peers.md.

func ParseVoices 

func ParseVoices(text string) (Voices, []Problem)

ParseVoices reads voices.md, reporting every defect.

func Rules 

func Rules() []finding.Rule

Rules describes the research checks.

Types

type Batch 

type Batch struct {
	Line        int
	Date        time.Time
	FromZero    bool
	Trigger     string
	Queries     string
	Unreachable string
	Shortfall   string
}

Batch is one dated research session.

type Evidence 

type Evidence struct {
	Line      int
	ID        int
	Publisher string
	Work      string
	Kind      string
	Published time.Time
	Precision Precision
	Fetched   time.Time
	Via       string
	Quote     string
	URL       string
	Applies   []string
	Observer  string
	Batch     int
}

Evidence is one fact from a standard, study, benchmark or guide.

type Evidences 

type Evidences struct {
	Title   string
	Batches []Batch
	Entries []Evidence
}

Evidences is evidence.md.

type GridRow 

type GridRow struct {
	Line   int
	Column string
	Value  string
	Peers  int
}

GridRow is one value of one fact and the number of peers showing it.

type Peer 

type Peer struct {
	Line    int
	ID      int
	Name    string
	URL     string
	Fetched time.Time
	Via     string
	Facts   map[string]string
	Batch   int
}

Peer is one peer newsletter.

type Peers 

type Peers struct {
	Title    string
	Batches  []Batch
	Entries  []Peer
	Grid     []GridRow
	GridLine int
	Baseline string
	Gaps     []string
}

Peers is peers.md. Grid, Baseline and Gaps are those of the latest batch that has them.

type Precision 

type Precision int

Precision is how exactly a source dates a post. 

const (
	Unknown Precision = iota
	Year
	Month
	Day
)

type Problem 

type Problem struct {
	Line    int
	Message string
	Hint    string
}

Problem is a format defect at a line.

type Report 

type Report struct {
	Findings  []finding.Finding
	Summary   Summary
	Voices    *Voices
	Peers     *Peers
	Evidences *Evidences
	// Complete is true when the minimums hold (or a shortfall is named) and nothing is malformed.
	Complete bool
}

Report is the result of checking the research directory.

func Check 

func Check(files map[string][]byte, dir string, today time.Time) Report

Check parses and checks the research files present in files (keyed by file name; absent files are skipped). dir prefixes names in findings.

func (Report) IDs 

func (r Report) IDs() map[string]bool

IDs returns every citable ID ("V001", "P003", "E101") in the report.

func (Report) Short 

func (r Report) Short() (voices, peers bool)

Short reports whether the voices and the peers each meet their minimums or name a shortfall.

type Summary 

type Summary struct {
	Voices    int `json:"voices"`
	Platforms int `json:"platforms"`
	Peers     int `json:"peers"`
	Evidence  int `json:"evidence"`
}

Summary describes the research a project stands on.

type Voice 

type Voice struct {
	Line      int
	ID        int
	Platform  string
	Place     string
	Author    string
	Posted    time.Time
	Precision Precision
	Fetched   time.Time
	Via       string
	Quote     string
	URL       string
	Observer  string
	Batch     int
}

Voice is one verbatim quote.

type Voices 

type Voices struct {
	Title   string
	Batches []Batch
	Entries []Voice
}

Voices is voices.md.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.