liveBook · Manning

High-level request

As explained in Writing for Developers: Blogs that get read

A high-level request is a review request that states the overall scope and kinds of feedback sought for a document.

A high-level request tells a reviewer what to examine across a document and what kinds of feedback would help. Name the scope instead of asking vaguely whether they like the draft. section 6.5.2

Shape the request around the reviewer’s perspective:

  • Ask technical reviewers to look for inadequate detail, factual errors, omissions, and irrelevant technical digressions. section 6.5.2
  • Ask clarity reviewers to flag missing context for the target reader, abrupt leaps, circular flow, and confusing sentences. section 6.5.2
  • Add article-wide questions to the review message and place part-specific questions as comments in the document. section 6.5.2

Avoid feedback-stifling prompts

Replace “How do you like it?” or “I think this is ready to go—let me know what you think” with a request that explicitly welcomes constructive criticism. section 6.5.2

How Writing for Developers: Blogs that get read covers it

How deep it goes
Defines review categories, distinguishes general from local questions, and warns against prompts that discourage criticism.
Examples
Uses technical and clarity review prompts plus contrasting vague and constructive request language.
What it assumes
Assumes a document, a reviewer, and a defined review perspective; teaches how to specify the request from there.
What you can do after
Apply it via a review message that elicits targeted, constructive feedback without constraining the reviewer.
How it connects
Connects technical review with clarity review, target readers, specific questions, and in-document comments.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Writing for Developers: Blogs that get read. The section links point to the parts of the book it draws on.