31 | {{ post.summary }} 32 |
33 | {% endif %} 34 |35 | 38 |
39 | {% if post.tags %} 40 |41 | {% for tag in post.tags %} 42 | {%- if tag != "post" -%} 43 | {% set tagUrl %}/tags/{{ tag }}/{% endset %} 44 | {{ tag }} 45 | {%- endif -%} 46 | {% endfor %} 47 |
48 | {% endif %} 49 | 50 | {% endfor %} 51 | 54 |15 | {{ page.data.summary }} 16 |
17 | {% endif %} 18 |19 | 22 |
23 | {% if page.data.tags %} 24 |25 | {% for tag in page.data.tags %} 26 | {%- if tag != "post" -%} 27 | {% set tagUrl %}/tags/{{ tag }}/{% endset %} 28 | {{ tag }} 29 | {%- endif -%} 30 | {% endfor %} 31 |
32 | {% endif %} 33 | 34 | {% endfor %} 35 |27 | {% for tag in post.data.tags %} 28 | {%- if tag != "post" -%} 29 | {% set tagUrl %}/tags/{{ tag }}/{% endset %} 30 | {{ tag }} 31 | {%- endif -%} 32 | {% endfor %} 33 |
34 | {% endif %} 35 | 36 |48 | {% for tag in tags %} 49 | {%- if tag != "post" -%} 50 | {% set tagUrl %}/tags/{{ tag }}/{% endset %} 51 | {{ tag }} 52 | {%- endif -%} 53 | {% endfor %} 54 |
55 | {% endif %} 56 | 57 |60 | Next: 61 | {{ nextPost.data.title }} 62 |
63 | {% endif %} 64 | {% if prevPost.url %} 65 |66 | Previous: 67 | {{ prevPost.data.title }} 68 |
69 | {% endif %} 70 | 73 | 74 |${entry.getIn(["data", "summary"], "")}
17 |21 | ${ 22 | entry.getIn(["data", "tags"], []).map( 23 | tag => 24 | html` 25 | ${tag} 26 | ` 27 | ) 28 | } 29 |
30 ||-|—|\n/g, '');
41 | //remove repeated spaces
42 | result = result.replace(/[ ]{2,}/g, ' ');
43 | // remove most emoji
44 | result = result.replace(/([#0-9]\u20E3)|[\xA9\xAE\u203C\u2047-\u2049\u2122\u2139\u3030\u303D\u3297\u3299][\uFE00-\uFEFF]?|[\u2190-\u21FF][\uFE00-\uFEFF]?|[\u2300-\u23FF][\uFE00-\uFEFF]?|[\u2460-\u24FF][\uFE00-\uFEFF]?|[\u25A0-\u25FF][\uFE00-\uFEFF]?|[\u2600-\u27BF][\uFE00-\uFEFF]?|[\u2900-\u297F][\uFE00-\uFEFF]?|[\u2B00-\u2BF0][\uFE00-\uFEFF]?|(?:\uD83C[\uDC00-\uDFFF]|\uD83D[\uDC00-\uDEFF])[\uFE00-\uFEFF]?/g, '');
45 |
46 | let match;
47 | while (match = regex.exec(result)) {
48 | const emoji = match[0];
49 | result = result.replace(emoji,' ')
50 | }
51 |
52 | return result;
53 | }
54 |
55 | return index.toJSON();
56 | };
--------------------------------------------------------------------------------
/loader.js:
--------------------------------------------------------------------------------
1 | if (localStorage.getItem('password')) {
2 | insertPlainHTML(atob(localStorage.getItem('password')))
3 | } else {
4 | document.getElementById('staticrypt-form').addEventListener('submit', function(e) {
5 | e.preventDefault();
6 | insertPlainHTML(document.getElementById('staticrypt-password').value);
7 | });
8 | }
--------------------------------------------------------------------------------
/manuscript/Book.txt:
--------------------------------------------------------------------------------
1 | why.md
2 | rules.md
3 | process.md
--------------------------------------------------------------------------------
/manuscript/manuscript.json:
--------------------------------------------------------------------------------
1 | {
2 | "layout": "layouts/page.njk"
3 | }
4 |
--------------------------------------------------------------------------------
/manuscript/process.json:
--------------------------------------------------------------------------------
1 | {
2 | "title": "The Writing Process",
3 | "eleventyNavigation": {
4 | "key": "The Writing Process",
5 | "order": 3
6 | }
7 | }
--------------------------------------------------------------------------------
/manuscript/process.md:
--------------------------------------------------------------------------------
1 | # The Writing Process
2 |
3 | Many people are under the impression that writing is a mystical
4 | -- or at least mysterious --
5 | activity, governed entirely by inspiration.
6 | While it is true that some authors work this way,
7 | waiting for inspiration to strike isn't a common strategy among professional writers,
8 | even novelists.
9 |
10 | For programmers and others writing non-fiction in a business context,
11 | there is a simple process that yields quality results.
12 |
13 | 1. Determine the goal
14 | 2. Determine the audience
15 | 3. Choose a suitable structure
16 | 4. Build an outline
17 | 5. Turn the outline into prose
18 | 6. Revise obvious weaknesses
19 | 7. Obtain feedback
20 | 8. Revise based on feedback
21 | 9. Publish
22 |
23 | In this chapter, we will walk through what each of these steps entail.
24 |
25 | ## 1. Determine the Goal
26 |
27 | ### Why am I writing this, anyway?
28 |
29 | Every time you start writing something,
30 | ask yourself, "Why?"
31 | Sometimes the answer is obvious,
32 | but often it's not.
33 | And even on those occasions when it is obvious,
34 | asking the question helps keep you focused on the goal.
35 |
36 | It's important to remember that we're trying to find the purpose of the document,
37 | not your personal motivation for writing it.
38 | If your answer to "Why am I writing this?" includes the words "I" or "me,"
39 | it is worth evaluating whether you're really thinking of the document's goal.
40 |
41 | For instance, if the answer to why you are writing a tutorial is,
42 | "So that I can get a raise,"
43 | you're thinking of the wrong thing.
44 | It's not that the motivation is _wrong_.
45 | It's just _irrelevant_ to producing a good tutorial.
46 | A better answer is,
47 | "To help others improve their game's performance."
48 |
49 | Because this answer is focused on what the audience receives,
50 | it is actually useful for guiding your writing efforts.
51 |
52 | ### Keep asking why.
53 |
54 | Often, the first goal we come up with will be superficial.
55 | "Teaching others how to use object pools,"
56 | may be accurate,
57 | and even somewhat useful,
58 | but a bit more context can be even more useful.
59 |
60 | There is a technique for root cause analysis called [5 Whys][],
61 | the premise of which is that you need to ask "Why?" multiple times to find the root cause of a problem.
62 | This technique also works well for determining a useful goal for writing.
63 |
64 | Suppose the first goal that occurs to you is
65 | "Teach developers how to use object pools."
66 | That is a perfectly clear and useful goal.
67 | But if you write only to that narrow goal,
68 | your readers won't know why the technique is useful.
69 | So ask yourself, "Why object pools?"
70 |
71 | Perhaps the answer is "To improve performance."
72 | But again we can ask "Why?"
73 | And our answer is something like, "To keep gameplay smooth."
74 |
75 | At this point we can state the goal as:
76 | "Teach game developers how to keep their games running smoothly by using object pools."
77 |
78 | With this more robust goal in mind we're more likely to communicate,
79 | not just the technique,
80 | but also its importance and trade-offs.
81 |
82 | ## 2. Determine the Audience
83 |
84 | Once we understand the goal of the document,
85 | we have enough information to start considering our audience.
86 | Our first question, though, takes a step back from the goal.
87 |
88 | ### Who will be reading this?
89 |
90 | Often the readership of documents is wider than we would initially expect.
91 | A framework's website will be read by developers, of course,
92 | but perhaps also:
93 |
94 | * Architects evaluating technology choices
95 | * Managers trying to keep abreast of what their team is using
96 | * Technical recruiters trying to understand the skillset they are hiring for
97 | * Designers trying to understand technical constraints on their designs
98 | * Sysadmins figuring out the framework's deployment features
99 |
100 | Take time to list the different types of potential readers.
101 | Doing so will help draw out whether additional supporting material is needed.
102 |
103 | ### Which readers are primary?
104 |
105 | Once you have the list of potential readers,
106 | refer back to the goal to decide which readers are most important.
107 | In most cases there will be a single group of readers who constitute your primary audience.
108 |
109 | Continuing the previous example:
110 | the primary audience of a framework website is developers.
111 | Others are important, but secondary to that audience.
112 |
113 | ### What is their relation to the subject?
114 |
115 | At this point we have our primary audience,
116 | but haven't given much detail about them.
117 | So it's time to consider their relation to the subject.
118 |
119 | One important axis to consider is their current level of expertise.
120 | Are they absolute beginners,
121 | world class experts,
122 | or somewhere in between?
123 | The answer to this question drives
124 | which sorts of things can be assumed
125 | and which need to be explained in great detail.
126 |
127 | Another axis is the readers emotional relationship with the subject.
128 | Are they intimidated, enthusiastic, or something else?
129 | A developer who fled Java for Ruby will have a very different attitude toward Haskell than a brand new developer.
130 | They may both be fearful,
131 | but about different things.
132 | Those emotional concerns also need to be addressed.
133 |
134 | ### What is their relation to you?
135 |
136 | In addition to the subject,
137 | we must also consider how the audience is related to you,
138 | the author.
139 | Are they coworkers?
140 | Then you can make certain assumptions about their familiarity with the business.
141 |
142 | Are you on friendly terms or is some of the audience hostile?
143 | You may need to focus more on your logical case for the latter.
144 |
145 | Are you part of the same culture/subculture?
146 | "Corporate suits" probably won't find image macros as amusing as your 22-year-old developer buddy.
147 |
148 | [5 Whys]: http://en.wikipedia.org/wiki/5_Whys
149 |
150 | ## 3. Choose a Suitable Structure
151 |
152 | Now that we know the goal and the audience
153 | we can consider how to structure the document to serve them.
154 |
155 | ### Choosing a structure based on the goal
156 |
157 | Goals can generally be placed on a spectrum between purely informational and purely persuasive.
158 | On one end of the spectrum,
159 | topical hierarchies are great at communicating lots of information efficiently.
160 | The hierarchy conveys the big picture while also supporting scanning through subtopics.
161 |
162 | At the other end of the spectrum,
163 | narrative is particularly effective at persuading people by engaging our natural sense of empathy.
164 | Telling a child that "Lying is a bad idea," is less likely to change their behavior than hearing _The Boy Who Cried Wolf_.
165 | For an example closer to our industry, consider _The Phoenix Project_:
166 | it vividly illustrates the problems of bureacratic IT departments
167 | as well as the benefits of embracing the DevOps movement.
168 |
169 | ### Choosing a structure based on the audience
170 |
171 | Your structure also needs to be suited to your audience.
172 |
173 | If your primary audience is developers with deep experience in your topic,
174 | then you may want to address them with an equally deep and detailed hierarchy of topics.
175 | A beginner, however, would likely benefit from a shallower step by step "recipe" guide.
176 |
177 | The reader's level of interest factors into which structure is best suited.
178 | A highly motivated reader may want to get right to the heart of the matter.
179 | But a distinterested reader
180 | --who is only looking at your document because his boss made him--
181 | may need to be enticed with a joke or anecdote explaining what is in it for him.
182 | That sort of reader will probably also need frequent positive reinforcement.
183 |
184 | The audience's relationship with you also makes a difference.
185 | If they are familiar with you and trust your judgment,
186 | they are more likely to be patient waiting for a payoff.
187 | But if they don't know anything about you,
188 | the internet is only a click away.
189 |
190 | ### Mixing and matching
191 |
192 | Most writing structures are relatively flexible
193 | and can be combined with other structures as warranted by the goal and the audience.
194 | **Don't be afraid to mix and match them.**
195 |
196 | For example, suppose that you need to convince business leaders that
197 | it is worthwhile to break your large monolithic application into several separate services.
198 | You'd probably start with a Problem-Solution structure like this:
199 |
200 | * Problems with the current architecture
201 | * Proposed solution
202 |
203 | In order to help the businesspeople make a decision, you'd probably extend it with a Pro-Con analysis as well.
204 |
205 | * Problems with the current architecture
206 | * Proposed solution
207 | * Costs and risks of change
208 | * Costs and risks of not changing
209 |
210 | A simple factual elaboration on that outline may win intellectual assent,
211 | but is unlikely to elicit wholehearted support from non-technical leaders.
212 | Why?
213 | Because they lack experiential knowledge of the problems, solutions, and risks.
214 |
215 | But parables and other metaphorical narratives can impart a degree of experiential knowledge without requiring actual experience.
216 | What sort of narrative would work in this case?
217 |
218 | Perhaps a story of a military building a single gigantic ship.
219 | It is powerful,
220 | but difficult to maneuver,
221 | and if it somehow fails then its entire arsenal is useless.
222 | (Business books are fond of military metaphors for some reason.)
223 | Then contrast this with building a fleet of small independently maneuverable ships.
224 |
225 | Revising the outline to incorporate this narrative gives us:
226 |
227 | * Problems with the current architecture
228 | * Parable of the dreadnought
229 | * Supporting factual details
230 | * Proposed solution
231 | * Parable of the fleet
232 | * Supporting factual details
233 | * Costs and risks of change
234 | * Refer to parable
235 | * Supporting factual details
236 | * Costs and risks of not changing
237 | * Refer to parable
238 | * Supporting factual details
239 |
240 | Combining these three structures creates a much more powerful and persuasive account than any of them alone.
241 |
242 | ## 4. Build an Outline
243 |
244 | With a structure
245 | (or set of structures)
246 | chosen for your project,
247 | it is time to build an outline.
248 | Some structures,
249 | like API documentation,
250 | may come with an outline template to follow.
251 | But many others,
252 | like the inverted pyramid,
253 | do not.
254 |
255 | This phase is all about taking your chosen structures
256 | and combining them with the details of your subject
257 | to produce the skeleton of your document.
258 |
259 | The outline itself is a simple hierarchical list of
260 | the things you want to communicate
261 | and the approach you want to take at each step.
262 | Particularly for smaller projects,
263 | the line between choosing a structure and outlining can be rather blurry.
264 | (Evidenced by the the section on choosing structures ending with an outline!)
265 | But an outline should show in detail **how** you intend to implement your chosen structure.
266 |
267 | ### How detailed should an outline be?
268 |
269 | This will likely vary from person to person,
270 | but I prefer to outline in enough detail that
271 | each low level bullet point corresponds to one or two paragraphs in the final text.
272 | This gives me sufficient guidance that I don't get lost,
273 | but also gives me enough flexibility to expand on some points without deviating from the outline.
274 |
275 | ### How do you actually create the outline?
276 |
277 | There are two basic approaches:
278 | depth-first
279 | and breadth-first.
280 | A depth-first approach starts at the top
281 | and explores all the way down to the details one point at a time.
282 | A breadth-first approach starts at the highest level
283 | and only becomes more detailed after all the higher level points have been filled in.
284 |
285 | **Partially completed depth-first outline**
286 |
287 | * Point 1
288 | * Point 1.1
289 | * Point 1.1.1
290 | * Point 1.1.2
291 | * Point 1.1.3
292 |
293 | **Partially completed breadth-first outline**
294 |
295 | * Point 1
296 | * Point 2
297 | * Point 3
298 | * Point 4
299 | * Point 5
300 |
301 | Breadth-first generally produces better results,
302 | because it provides more overall context each time we step down a level of detail.
303 | That extra context makes it much less likely that we will get stuck on trivia.
304 |
305 | ### Evaluate and revise
306 |
307 | Once you've drafted your outline,
308 | be sure to evaluate it with your goals and audience in mind.
309 | It is much easier to move or edit a few bullet points
310 | than to revise entire sections of your document.
311 |
312 | ## 5. Turn the outline into prose
313 |
314 | Everything we've talked about so far has been aimed at preparing you for this part of the process.
315 | You should know your goal, audience and structure.
316 | And your outline gives you a game plan.
317 | Now it's time to turn all that into something for others to read.
318 |
319 | ### Putting flesh on the bones
320 |
321 | Right now what you've got is a skeleton.
322 | It's vaguely in the shape you want,
323 | but if it tried to walk around it would quickly fall apart.
324 | There are two principle things that it is lacking:
325 | muscle to give it strength,
326 | and ligaments to hold things together.
327 | Let's start with the muscle.
328 |
329 | Bare statements of fact rarely carry much weight with readers,
330 | regardless of how important those facts might be.
331 | They have to be elaborated on
332 | and placed into their proper context.
333 | And usually the most important context for a reader is the answer to
334 | "Why do I care about this?"
335 | A reason to care gives your prose strength.
336 |
337 | Consider this example:
338 |
339 | > Continuous integration improves the development process.
340 |
341 | > Continuous integration improves the development process by helping us detect defects sooner.
342 | > That means fewer late night calls to debug production.
343 |
344 | The latter includes more supporting detail about _how_ it helps,
345 | as well as a reason for developers to care about it.
346 |
347 | In addition to muscle we need ligaments.
348 | The ligaments are what actually connects one bone to another.
349 | The prose equivalent is a transition.
350 |
351 | Sudden jumps from one topic to another
352 | (even closely related)
353 | are jarring.
354 | Transitions serve to smooth that over by
355 | clearly signaling the close of one topic,
356 | the introduction of the next,
357 | and possibly how they are related.
358 |
359 | A transition can be a simple phrase.
360 | It can be an entire sentence.
361 | It can be a paragraph.
362 | Or multiple paragraphs.
363 | It all depends on the size of the pieces you're transitioning between.
364 |
365 | For an example, take a look at the paragraph that started this section (#5) above.
366 |
367 | ### It's not necessarily exposition
368 |
369 | When working from your outline,
370 | beware of always choosing the most direct expansion of your points.
371 | Simple exposition is the most common way of describing things,
372 | but it isn't always the best.
373 | Using other forms of expansion will give your prose variety and help maintain reader interest.
374 |
375 | Especially in a longer text,
376 | including the occasional story, joke, or anecdote
377 | can make the difference between a pleasant read or an unbearably boring one.
378 |
379 | Whatever you choose to use,
380 | it should be integrally related to the points you're trying to make.
381 |
382 | There is a story about a high school student who had to give a book report.
383 | When he stood up in front of the class he yelled,
384 | "Sex! Sex! Sex!"
385 | then continued,
386 | "Now that I have your attention,
387 | I'd like to talk to you about The Complete History of World War II."
388 |
389 | Don't be like the high school student.
390 |
391 | ## 6. Revise
392 |
393 | At this point you have a fleshed out draft,
394 | so now it is time to fix the gaps and rough edges.
395 |
396 | ### Evaluate
397 |
398 | Starting at the beginnning, read each unit of your work.
399 | Depending on the length of your document, that unit might be a paragraph, section, or chapter.
400 | As you read, ask yourself the following questions:
401 |
402 | * Does this advance the goal?
403 | * Is it clear?
404 | * Is it concise?
405 | * Is it well organized?
406 | * Is it scannable?
407 |
408 | You'll likely want to read the unit multiple times to answer these questions.
409 | For a longer unit, one read per question -- or even more -- may be appropriate.
410 |
411 | > #### Tip: Try different contexts
412 | >
413 | > Reading in a different context than you usually write in can help you to see things differently and spot problems more easily.
414 | > For example, if you usually write at a computer,
415 | > try printing your document out on paper,
416 | > or even reading it out loud.
417 |
418 | ### Plan your corrections
419 |
420 | Take notes on each thing that needs to be improved,
421 | but don't make corrections right away.
422 | Introducing a slight delay between identifying the problem and attempting to fix it
423 | will give your mind a chance to work on the problem,
424 | and often arrive at a better solution than the first one you thought of.
425 |
426 | Your notes can take many forms:
427 | a separate text file,
428 | using Track Changes in Microsoft Word,
429 | and so on.
430 | I tend to prefer annnotating a physical paper with pen or pencil,
431 | but you should experiement and find what works best for you.
432 |
433 | After you have a list of all the corrections you plan to make,
434 | you may be able to spot common patterns for future improvement.
435 | But the immediate task is to begin making corrections.
436 |
437 | ### Make your corrections
438 |
439 | Proceed through your notes from beginning to end,
440 | correcting each problem.
441 | If you get stuck on something,
442 | leave it to the side for now.
443 | You'll come back to it later.
444 |
445 | Once you've completed all the corrections you were able to make,
446 | take another look at any you left behind.
447 | You may know how to fix them now.
448 | If so, go ahead.
449 | If not, we'll leave them for the next stage of the writing process: feedback.
450 |
451 | ## 7. Get feedback
452 |
453 | Up to this point everything has come from you,
454 | even thinking about the audience.
455 | But this is where you actually engage with other people for the first time.
456 | Brace yourself,
457 | because feedback from real people is almost certain to suprise you,
458 | regardless of whether it's positive or negative.
459 |
460 | ### Sources of feedback
461 |
462 | Generally you will be getting feedback from one of three types of readers:
463 | members of the target aurdience,
464 | experts on the subject,
465 | and friends/coworkers.
466 | Each of these groups has strengths and weaknesses.
467 | Getting feedback from all three is ideal,
468 | and occasionally the groups overlap,
469 | but feedback from any of them is useful for checking your assumptions.
470 |
471 | #### Target audience
472 |
473 | Members of the target audience are extremely valuable
474 | because they can tell you whether your writing is achieving the intended goal.
475 | Unfortunately, they often can't tell you why.
476 | And even if they do offer a reason,
477 | it shouldn't always be taken at face value.
478 |
479 | To help overcome this issue,
480 | it can help to supply a list of specific questions for them to answer.
481 | For example:
482 |
483 | * By the end did you think that it is worth investigating the new technology I described?
484 | * If not, was there a specific point where I lost you?
485 | * Did any of my supporting evidence seem questionable?
486 |
487 | Unfortunately, it can be difficult or impossible to get feedback from the audience.
488 | After all, when drafting an email to your boss's boss,
489 | you can't very well ask them to proofread it.
490 |
491 | #### Experts
492 |
493 | Expert feedback can also be very useful,
494 | particularly for identifying inaccuracies and mistakes.
495 | One issue to watch out for, though,
496 | is that experts may not remember what it was like to be a beginner.
497 | So if beginners and non-experts are in your target audience,
498 | be careful of suggestions to includes lots of additional details which they won't have the context to understand.
499 |
500 | #### Friends and coworkers
501 |
502 | Friends and coworkers are often the easiest reviewers to obtain.
503 | Unfortunately, they are often the least reliable in providing needed correction.
504 | No one wants to hurt the feelings of someone they like.
505 | But they are often excellent at providing encouragement,
506 | and when working on a large writing project,
507 | that can be invaluable.
508 |
509 | ### Evaluating feedback
510 |
511 | When evaluating the feedback there are a few principles to keep in mind.
512 |
513 | First, _readers are always right about their reactions_.
514 | If a reader says that they were confused by a certain point,
515 | then they were,
516 | no matter how clear it may appear to you.
517 |
518 | Second, _a reader's negative reaction does not automatically lead to revision_.
519 | It is your responsibility to evaluate
520 | whether issues raised are actually problems for your target audience
521 | and serious enough to require addressing.
522 |
523 | Third, _a reader's proposed solution may not be correct_.
524 | Sometimes readers will suggest solutions without explaining the problem they identified.
525 | For example, "I think you need a fancy graphic right here."
526 | This suggestion might be a good one,
527 | but you should work to understand the underlying problem.
528 | Perhaps the text became boring,
529 | or perhaps a diagram would help with clarity.
530 | Whatever the case may be,
531 | don't just take the suggestion at face value.
532 |
533 | Finally, _a reader's feedback should be weighted differently based on who they are and what area their feedback is in._
534 | An expert's feedback regarding correctness should be prioritized over a beginner's,
535 | and an audience member's feedback regarding readability should be prioritized over the expert's.
536 |
537 | ### Compile the feedback into revision notes
538 |
539 | After taking all of this in,
540 | you should have a list of changes to make.
541 | And you may also have a list of positive points which you should try to retain.
542 | Despite the focus on improving problems,
543 | you also don't want to edit away something that is working.
544 |
545 | ## 8. Revise based on feedback
546 |
547 | Just like with your first revision notes,
548 | you will go back through and make your changes one at a time,
549 | evaluating the criteria of clarity, concision, organization, scannability and goal focus.
550 | By the time you are done,
551 | you should have a pretty solid draft.
552 |
553 | As you revise, make changes one at a time,
554 | assessing clarity, concision, organization, scannability, and goal focus.
555 | Pay attention to common themes in the feedback you receive.
556 | Those are the ones most likely to require revision.
557 |
558 | Remember to prioritize the most significant changes first.
559 | Tackle issues like organization or persuasiveness before minor details like grammar.
560 | Getting something grammatically correct is a waste of time
561 | if that entire section will be reworked or removed.
562 | Throughout revision, continuously review your goals and audience,
563 | and be prepared for multiple rounds of changes.
564 |
565 | After you've revised, seek additional feedback,
566 | both to verify initial concerns are addressed
567 | and to ensure no new problems have been introduced.
568 | Consult with both original and new readers to get different perspectives.
569 | Remember, continuous revision is crucial for producing a polished and effective piece of writing.
570 |
571 | ## 9. Publish
572 |
573 | Publishing your work is usually the most critical part of the writing process,
574 | but remember, it can happen at any point, depending on the project.
575 | In some cases, publishing might be part of an ongoing process,
576 | with updates and revisions made after the first release.
577 | This is especially true for things like wiki-based technical documentation
578 | or presentations that are given multiple times and need tweaks based on audience feedback.
579 |
580 | Before you publish, think about the context and the level of polish your writing needs.
581 | Not every situation calls for super polished writing.
582 | A quick email to a coworker won't need the same level of refinement as a formal report for the big boss.
583 | Adapt the level of polish to the context so you strike the right balance between quality and getting things done.
584 |
585 | Before hitting that publish button,
586 | give your work a once-over for any errors or inconsistencies,
587 | and make sure your formatting looks good,
588 | based on what's required in your situation.
589 | This final check is crucial for presenting your writing in the best light.
590 |
591 | After publishing, don't forget to spread the word.
592 | Share your work with the people who need to see it,
593 | whether that's passing a report to colleagues,
594 | posting a blog on social media,
595 | or presenting your findings at a conference.
596 | Keep in mind that publishing doesn't mean you're done with revisions.
597 | Be open to feedback even after your work is out there,
598 | and be ready to make updates or corrections as needed.
599 | Embracing this back-and-forth will help you keep improving your writing skills
600 | and adapt to the needs of your audience in all kinds of situations.
601 |
602 | ## Summing it up
603 |
604 | The writing process is all about striking the right balance between the formal process and the needs of the situation.
605 |
606 | From setting goals and figuring out who you're writing for,
607 | to making an outline,
608 | revising,
609 | and hitting that publish button,
610 | each step is important.
611 | But not equally important.
612 |
613 | Keep an eye on your context and switch things up as needed,
614 | whether it's the level of polish or the amount of feedback and revision you're going for.
615 | Don't forget, the process can and should be trimmed down when it makes sense for the situation,
616 | helping you focus on what's most important in each specific context.
617 | The more you work at it, the better you'll get at writing and connecting with your audience.
618 |
619 | Writing takes time, practice, and being open to learning from both the things you nail and the things you, well, don't.
620 | As you gain experience as a writer,
621 | you'll find that this whole process starts to feel more natural,
622 | and your ability to get your point across will only get better.
623 | Just keep writing, learning, and tweaking your process to fit each unique writing situation you find yourself in.
--------------------------------------------------------------------------------
/manuscript/rules.json:
--------------------------------------------------------------------------------
1 | {
2 | "title": "General Rules",
3 | "eleventyNavigation": {
4 | "key": "General Rules",
5 | "order": 2
6 | }
7 | }
--------------------------------------------------------------------------------
/manuscript/rules.md:
--------------------------------------------------------------------------------
1 | # General Rules
2 |
3 | Rules.
4 | The very word can trigger skepticism.
5 | And understandably so.
6 | We are often confronted with seemingly arbitrary rules
7 | which make our lives harder for no apparent reason.
8 |
9 | In this chapter I will give you rules to follow,
10 | but I will also explain each rule's rationale.
11 | So if you find yourself in a situation beyond the scope of the rule,
12 | you'll be equipped to make intelligent decisions about how or if to apply it.
13 |
14 | It is also important to acknowledge the limits of these rules.
15 | They are targeted principally at writing within a professional business context.
16 | If you are writing a novel,
17 | these rules will be of limited use.
18 | And if you are writing poetry,
19 | they will probably be entirely useless.
20 | But if you need to communicate ideas to your coworkers,
21 | then these rules will serve you well.
22 |
23 | Now that we've set the appropriate context, let's look at those rules.
24 |
25 | ## 1. Be goal oriented.
26 |
27 | > "In my end is my beginning."
28 | >
29 | > -- T.S. Eliot
30 |
31 | ### Everything you write has a goal
32 |
33 | Suppose a boss or client came to you and said they needed you to build a web application.
34 | Your first question would probably be,
35 | "What is the application for?"
36 | The very idea of writing an application without knowing its purpose is ridiculous.
37 | Yet when it comes to writing prose,
38 | we too often fail to ask the obvious question.
39 |
40 | Everything you write has a goal,
41 | whether explicit or implicit.
42 | Those API docs?
43 | The stated goal is to inform other developers how to use your library.
44 | That weekly status report you email your client?
45 | The unstated goal is reassuring them that their money is being well spent.
46 |
47 | The goal of a document isn't always obvious,
48 | but in the next chapter, we'll look at some tools to figure it out.
49 |
50 | ### Knowing the goal equips you to fulfill it.
51 |
52 | Let's go back to our hypothetical web application above.
53 | Suppose you did try to build it without actually knowing its purpose?
54 | You are just given a list of features and told to start building.
55 | What would happen?
56 |
57 | You'd have no way to evaluate how well or poorly the application was doing.
58 | And that's not just a problem at the end.
59 | All along you'd have questions about how best to build each feature.
60 | But without knowing the application's purpose,
61 | you'd have no way of choosing between the alternatives.
62 | That kind of uncertainty is crippling.
63 | And I suspect that is why many people avoid writing.
64 |
65 | But when you do know the goal you are writing toward,
66 | decisions are easier,
67 | and it is simpler to tell whether your writing succeeds in achieving its end.
68 |
69 | ### The structure of goals
70 |
71 | We've talked about goals a lot,
72 | but so far we haven't really clarified what kind of goals we're talking about.
73 | It's all about the document.
74 |
75 | In this book,
76 | when I talk about goals,
77 | I mean the purpose intrinsic to the document[^telos],
78 | not the author's personal motivations.
79 | For instance,
80 | your goal in writing API docs may be to keep your tech lead from bugging you about it yet again.
81 | But the purpose of the docs themselves is to assist users of the API.
82 |
83 | A document's goals will generally fall into one of two categories:
84 | to inform or to persuade.
85 | Most documents will include a bit of both,
86 | but one will be primary.
87 | To go back to the API docs example,
88 | it may help persuade people to use your library,
89 | but the primary purpose is just to inform them about how to do so.
90 |
91 | [^telos]: If you're familiar with ancient Greek philosophy,
92 | this is what Aristotle would call the document's _telos_.
93 |
94 | ## 2. Be concise.
95 |
96 | In a professional context,
97 | everyone is pressed for time.
98 | Being concise is about respecting your readers' time.
99 | Don't force them to read a page when a paragraph will do.
100 |
101 | Conciseness also helps you achieve your goal.
102 | The more time investment your text requires,
103 | the more reluctant readers will be to give it to you.
104 | So we should do our best to keep the required investment to a minimum.
105 |
106 | At the same time, conciseness does not mean being excessively terse.
107 | Conciseness means saying the exact amount necessary to achieve the goal:
108 | no more and no less.
109 |
110 | ## 3. Be Clear
111 |
112 | ### Avoid ambiguity
113 |
114 | Human language is rife with ambiguity.
115 | Take as an example my first title idea for this book:
116 | "Writing for Developers."
117 | Only three words,
118 | yet it could be read in two totally different ways.
119 | That title could have meant
120 | -- as I intended --
121 | "A book for developers on the subject of writing."
122 | But another equally reasonable interpretation was,
123 | "A book on writing for an audience of developers."
124 |
125 | Ambiguous language is useful in art and poetry,
126 | but not when we are trying to communicate as efficiently as possible.
127 |
128 | ### Avoid jargon
129 |
130 | It is also wise to avoid unfamiliar terms and jargon.
131 | Of course, this is dependent on your audience.
132 | To a developer, this sentence makes perfect sense:
133 |
134 | > "Hoth is a lightweight MVVM framework
135 | > which leverages dirty checking
136 | > and immutable data structures for performance."
137 |
138 | To a non-developer,
139 | it sounds more like this:
140 |
141 | > Hoth is a lightweight magic framework
142 | > which leverages scary magic
143 | > and scarier magic for performance.
144 |
145 | For readers unfamiliar with the terminology it communicates next to nothing.
146 |
147 | ### Narrow the scope of your words
148 |
149 | We love to speak in generalities.
150 | Perhaps because it is difficult to definitely prove a generality wrong.
151 | The problem is that the more general a statement is,
152 | the more difficult it is to understand and apply.
153 | Consider this example:
154 |
155 | > Object-oriented programming is terrible.
156 |
157 | It's not completely meaningless,
158 | but it is extremely broad,
159 | and the implications are unclear.
160 | Should readers avoid all object oriented languages?
161 | It's hard to tell what the author is thinking.
162 |
163 | Contrast with this:
164 |
165 | > Class-based inheritance tends to make code unnecessarily complex.
166 |
167 | This version has narrowed the scope in two ways.
168 | It has narrowed from all object-oriented programming to class-based inheritance.
169 | And it has narrowed from "terrible" to "tends toward unnecessary complexity."
170 | As a result,
171 | this sentence is much easier to understand and evaluate.
172 |
173 | Given the choice between the specific and the general, choose the specific.
174 |
175 | ## 4. Be organized.
176 |
177 | For many people this is the most difficult part.
178 | They know the goal.
179 | They can write clear, concise sentences.
180 | But they have a hard time putting those pieces together into a coherent whole.
181 |
182 | In the next chapter we'll look at how to do it.
183 | For now let's explore why.
184 |
185 | ### Structure aids comprehension
186 |
187 | The human mind is built for pattern matching.
188 | And it is pretty good at its job,
189 | otherwise we'd have all been eaten by tigers long ago.
190 |
191 | Consider two different lists:
192 |
193 | * Apple pie
194 | * Blueberry pie
195 | * Cranberry pie
196 |
197 | * Wrench
198 | * Justice
199 | * Puppy
200 |
201 | The first list is much more memorable and comprehensible.
202 | Why?
203 | Because it is organized into a structure that our minds can easily extract.
204 | Each item in the list was a pie.
205 | Each of the pies was fruit-based.
206 | And the pies were alphabetically ordered.
207 | But the second list had no unifying organizational structure.
208 |
209 | ### Structure is fractal
210 |
211 | Writing structures are simultaneously high level and low level.
212 | They encompass everything
213 | from your three main points
214 | to that sub-sub-sub-point in paragraph 45.
215 | And if you've chosen your structure well,
216 | the micro and macro levels will tend to mirror each other.
217 | For example, consider this outline for an article on the Hoth Framework.
218 |
219 | > * Intro to Hoth
220 | > * Immutable data structures
221 | > * Intro
222 | > * Benefits
223 | > * Examples
224 | > * Dirty checking
225 | > * Intro
226 | > * Benefits
227 | > * Examples
228 | > * Example application
229 | > * Conclusion
230 |
231 | Both of the main sub-points follow the same structure as the outline as a whole.
232 | The mirroring isn't always this obvious,
233 | but it is generally present.
234 |
235 | ### Projects may come with built-in structure
236 |
237 | Certain kinds of projects come with ready-made,
238 | very detailed structures,
239 | simply because of how common that type of project is.
240 | API docs,
241 | for example,
242 | may vary a bit by language,
243 | but will generally look pretty close to this.
244 |
245 | * Modules
246 | * Name
247 | * Description
248 | * Classes
249 | * Name
250 | * Description
251 | * Methods
252 | * Name
253 | * Arguments
254 | * Return value
255 | * Description
256 |
257 | Not every predetermined structure is that specific, though.
258 | Library websites have several things they need to include,
259 | like language,
260 | purpose of the library,
261 | and how to install it,
262 | but they also have more flexibility.
263 |
264 | ### General purpose structures
265 |
266 | In addition to these very specific structures,
267 | there are also many general purpose structures.
268 | These are things like the inverted pyramid, objection-response, etc.
269 |
270 | Typically you will pick two or three of these general purpose structures
271 | and use them as the organizing principle of the project.
272 |
273 | ## 5. Be scannable.
274 |
275 | While the previous rule was about the conceptual structure of a text,
276 | this rule is about the visual typographic structure.
277 | The point of scannability is to allow readers to locate important information at a glance,
278 | rather than reading every word on the page.
279 | Even for readers that do read every word,
280 | scannable typography makes it easier to refer back to key ideas in the text.
281 |
282 | ### Break text into bite-sized pieces
283 |
284 | Have you ever read a paragraph that took up an entire printed page?
285 | They are no fun to read.
286 | With no visual breaks,
287 | it is difficult to keep track of where you are,
288 | much less follow the flow of ideas.
289 |
290 | To maximize scannability,
291 | text should be broken into bite-sized units of thought.
292 | Paragraphs, for example, should generally be 2-5 sentences long.
293 | Much longer and it becomes difficult to read.
294 | Shorter and you may want to use a heading instead.
295 |
296 | ### Divide and conquer with headings
297 |
298 | The primary purpose of headings is to make your text's conceptual structure explicit.
299 | However, they also have two important scannability implications.
300 |
301 | First, headings provide a visual anchor allowing readers to locate where a concept is discussed.
302 |
303 | Second, headings breaks the text into units of progress which help the reader stay motivated to continue.
304 | This is part of the reason list posts are such a popular article format.
305 | Each time the reader reaches the next heading,
306 | they get to cross something off their mental checklist.
307 |
308 | ### Use lists for your lists
309 |
310 | While not as common as paragraphs,
311 | the humble list is one of the author's most helpful tools.
312 | It provides:
313 |
314 | * Visual attraction for the list
315 | * Visual attraction for each item in the list
316 | * A break from the monotony of paragraphs
317 | * A sense of progress
318 |
319 | You can, of course, embed lists directly into your sentences and paragraphs.
320 |
321 | > While not as common as paragraphs,
322 | > the humble list is one of the author's most helpful tools.
323 | > It provides:
324 | > visual attraction for the list,
325 | > visual attraction for each item in the list,
326 | > a break from the monotony of paragraphs,
327 | > and a sense of progress.
328 |
329 | However, doing so relegates the list contents to a secondary status.
330 | In general,
331 | using typographic lists
332 | (bulleted, numbered, etc.)
333 | for your conceptual lists makes sense if the exact contents are worth emphasizing.
334 |
335 | ### Emphasize key ideas with bold or italics
336 |
337 | Ordinary paragraphs are the parts of a text most likely to be skipped over.
338 | But sometimes important ideas only make sense as part of a paragraph.
339 | That's where typographic emphasis comes in.
340 |
341 | Highlighting important ideas with bold or italics allows readers to see key ideas at a glance.
342 |
343 | However, there are some rules of thumb to keep in mind.
344 |
345 | * Only highlight one phrase or sentence per paragraph.
346 | * Don't highlight something in _every_ paragraph.
347 | * **Never** highlight something with both bold and italics.
348 |
349 | Go beyond these limits and readers are likely to feel that you are shouting at them.
--------------------------------------------------------------------------------
/manuscript/why.json:
--------------------------------------------------------------------------------
1 | {
2 | "title": "Why should developers study writing?",
3 | "eleventyNavigation": {
4 | "key": "Why should developers study writing?",
5 | "order": 1
6 | }
7 | }
--------------------------------------------------------------------------------
/manuscript/why.md:
--------------------------------------------------------------------------------
1 | # Why should developers study writing?
2 |
3 | If you've picked up this book, then you're probably a software developer.
4 | Furthermore, you're someone who cares about your career.
5 | You've probably spent countless hours
6 | studying manuals,
7 | reading library docs,
8 | learning how to write clean code,
9 | and otherwise mastering your craft.
10 |
11 | But you may be skeptical.
12 | There are a thousand other things you could learn.
13 | Why spend the time studying writing?
14 | Let's walk through some of the things you might be thinking.
15 |
16 | ## I'm paid to code, not to write.
17 |
18 | In most cases, developers aren't paid to code.
19 | We are paid to produce working software that solves a business problem.
20 | In order to do that we may need to:
21 |
22 | * Email a product manager to clarify a requirement
23 | * Instant message a designer to verify the color and placement of a call-to-action button
24 | * Document the details of an internal REST API
25 | * Submit a patch to an open-source project you use
26 | * File a bug report about a part of the software developed by another team
27 | * Provide explanatory notes about that spike in server errors on the 14th
28 | * Tweak the wording of some UI text that is confusing users,
29 | since the designer is unavailable
30 |
31 | All of these things are run of the mill tasks for a software developer.
32 | And every single one of them is a form of writing.
33 |
34 | ## I already know how to write. I did well in school.
35 |
36 | Unfortunately, literacy,
37 | even at college or university level,
38 | doesn't guarantee the ability to write effectively.
39 | Many degree programs place little emphasis on writing.
40 | And those that do emphasize it often encourage an academic style which doesn't mesh well with most developer's jobs.
41 |
42 | Academic writing tends to value a kind of distant objectivity which can manifest as:
43 |
44 | * Unnecessary jargon
45 | * Verbose and indirect prose
46 | * Extreme formality
47 |
48 | In contrast, most developers would benefit from making their prose clear, direct, and concise.
49 |
50 | ## But I could be studying the Hoth framework instead. It's so cool!
51 |
52 | Yes, no matter which topic you decide to study,
53 | you will be passing up something else.
54 | But writing deserves special consideration.
55 | Why?
56 | **Because writing is a durable skill.**
57 |
58 | Technology changes quickly.
59 | If you're not careful,
60 | you can easily invest a lot of time and energy into a technological one hit wonder.
61 | Writing, though, will never be rendered obsolete by the fickle winds of technology or fashion.
62 |
63 | **Writing is also a transferable skill.**
64 | If you decide to change careers and become a
65 | realtor,
66 | landscape artist,
67 | or -- God forbid! -- a manager,
68 | your expertise in the Hoth MVVM framework will be of limited use.
69 | But writing will remain.
70 |
71 | ## But what will I get out of studying writing?
72 |
73 | ### Less back and forth
74 |
75 | We've all experienced out of control email threads.
76 | It starts with a vague question,
77 | is usually followed by an ambiguous answer,
78 | and before you know it,
79 | someone in another department is freaking out about a non-existent problem.
80 |
81 | What if you could step in and make people understand?
82 | Even better, what if you could prevent the issue from escalating in the first place?
83 | That's the power of clear and effective writing.
84 |
85 | ### Fewer bugs and less rework
86 |
87 | Sometimes we run across frustratingly mysterious bits of code.
88 | Perhaps we've even written some ourselves.
89 | But what's even more frustrating
90 | is when the code is accompanied by an equally mysterious comment like,
91 | "fixes IE bug."
92 |
93 | What IE bug? And which version of IE?
94 |
95 | A developer working on this code, now needs to:
96 |
97 | * Talk to the original programmer,
98 | who won't remember anything.
99 | * Manually test to see if there are obvious bugs related to that line,
100 | which he probably won't catch.
101 | * And perhaps make changes anyway,
102 | without knowing what he broke.
103 |
104 | A clearly written comment would have prevented all of that.
105 |
106 | ### Protect your development flow
107 |
108 | Talking face to face is a valuable and necessary part of our jobs.
109 | But not every face to face conversation is valuable.
110 |
111 | If you find yourself explaining certain things over and over again
112 | (perhaps because you're an expert in a particular subsystem)
113 | then you should write it down in a public location like a team wiki.
114 | If your explanations are clear and easy to understand,
115 | you'll have fewer interruptions messing with your development flow.
116 |
117 | ### Recognition of your expertise
118 |
119 | Perhaps you have a different problem.
120 | You have a deep knowledge of some tool, library, or system,
121 | but no one realizes it.
122 | Writing guides, tutorials, and presentations
123 | can help you achieve greater recognition,
124 | both inside and outside your company.
125 |
126 | ### Greater trust from managers
127 |
128 | Watching a software development project from the outside can be a frustrating experience.
129 | This is doubly true if you are on the hook when something goes wrong.
130 |
131 | A developer who can clearly articulate the state of the project,
132 | without getting bogged down in technical details,
133 | is invaluable.
134 |
135 | If you are that developer,
136 | you will quickly earn the trust of your manager and non-technical colleagues.
137 |
138 | ### Improve your own understanding
139 |
140 | > "How can I tell you what I think till I see what I say?"
141 | >
142 | > -- E.M. Forster, _Aspects of the Novel_
143 |
144 | The process of writing takes our often fuzzy and unformed ideas,
145 | and shapes them into something clear enough to communicate to others.
146 | This makes writing an excellent way to deepen our own understanding of a subject.
147 | Sometimes the improvement comes from research,
148 | but often it comes simply due to organizing our own thoughts.
149 |
150 | ## What now?
151 |
152 | Hopefully by this point you can see why studying writing is worthwhile.
153 | In the next chapter,
154 | we'll launch into some general rules you can use to improve your writing.
--------------------------------------------------------------------------------
/netlify.toml:
--------------------------------------------------------------------------------
1 | [build]
2 | publish = "_site"
3 | command = "npm run build"
4 | #command = "npm run build && set -e && find ./_site -type f -name '*.html' -exec staticrypt -f password_template.html {} $PASSWORD -o {} \\;"
5 | functions = "functions"
6 |
7 | # REDIRECT and HEADERS examples
8 |
9 | # Redirect rule example
10 | # For more information see:- https://www.netlify.com/docs/netlify-toml-reference/
11 |
12 | #[[redirects]]
13 | # from = "/*"
14 | # to = "/blog/:splat"
15 |
16 | # The default HTTP status code is 301, but you can define a different one e.g.
17 | # status = 302
18 |
19 | # Headers rule example
20 | # For more information see:- https://www.netlify.com/docs/netlify-toml-reference/
21 |
22 | #[[headers]]
23 | # Define which paths this specific [[headers]] block will cover.
24 | # for = "/*"
25 |
26 | #[headers.values]
27 | # X-Frame-Options = "DENY"
28 | # X-XSS-Protection = "1; mode=block"
29 | # Content-Security-Policy = "frame-ancestors https://www.facebook.com"
30 |
31 | # Redirects and headers are GLOBAL for all builds – they do not get scoped to
32 | # contexts no matter where you define them in the file.
33 | # For context-specific rules, use _headers or _redirects files, which are
34 | # applied on a PER-DEPLOY basis.
35 |
--------------------------------------------------------------------------------
/outline.md:
--------------------------------------------------------------------------------
1 | # Prose for Programmers Outline
2 |
3 | Checked boxes indicate that the initial draft of a section is complete.
4 |
5 | ## [Why should developers learn to write?](manuscript/why.md)
6 |
7 | - [x] Objections
8 | - [x] Paid to code, not write
9 | - [x] Laundry list of writing developers have to do
10 | - [x] Coding is writing
11 | - [x] I already know how to write. I did well in school.
12 | - [x] Literacy, even college level, doesn’t mean your writing is good
13 | - [x] Academics can even foster bad writing habits
14 | - [x] But I could be learning technology X instead
15 | - [x] Writing is a durable skill
16 | - [x] Writing is a transferable skill
17 | - [x] Benefits
18 | - [x] fewer back and forth emails/chats
19 | - [x] Fewer bugs due to misunderstood code/docs
20 | - [x] Fewer interruptions from coworkers with questions (keep flow)
21 | - [x] More understanding/empathy from managers
22 | - [x] Recognition of your knowledge
23 | - [x] Increase your own understanding
24 |
25 | ## [General Rules](manuscript/rules.md)
26 |
27 | - [x] Be goal oriented
28 | - [x] Everything you write has a goal or purpose
29 | - [x] may be implicit or explicit
30 | - [x] Understanding the goal promotes better writing
31 | - [x] Structure of goals
32 | - [x] 2 types
33 | - [x] inform
34 | - [x] persuade
35 | - [x] Most writing serves both to one degree or other
36 | - [x] But most writing has a primary goal, with others as secondary
37 | - [x] Be concise
38 | - [x] Not short or terse
39 | - [x] Everything contributes to the goal
40 | - [x] Avoids wordiness for the sake of the goal
41 | - [x] Be clear
42 | - [x] Avoid unfamiliar or unnecessary jargon
43 | - [x] Avoid ambiguity
44 | - [x] Be precise
45 | - [x] Be organized
46 | - [x] Human mind uses patterns to extract meaning
47 | - [x] Structure is fractal: macro and micro mirror each other
48 | - [x] Projects may come with built-in structure (API docs)
49 | - [x] Several general purpose structures available
50 | - [x] Be scannable
51 | - [x] Typographic structure to direct attention to ideas
52 | - [x] Break up text into digestible chunks
53 | - [x] use headlines
54 | - [x] use lists
55 | - [x] Make use of bold and italic to highlight points
56 |
57 | ## [The Writing Process](manuscript/process.md)
58 |
59 | - [x] Determine the goal
60 | - [x] Why am I writing this?
61 | - [x] Purpose of doc
62 | - [x] Not personal motivations
63 | - [x] Keep asking why
64 | - [x] Determine audience
65 | - [x] Who will be reading this?
66 | - [x] Given the goals, which readers are the primary audience?
67 | - [x] What is their relation to the subject?
68 | - [x] What is their relation to you?
69 | - [x] Examples of how audience affects writing
70 | - [x] Choose a suitable structure
71 | - [x] Different structures are suitable for different goals
72 | - [x] Hierarchical structures are often good for informational
73 | - [x] Narrative is good for persuasive
74 | - [x] Different structures for different audiences
75 | - [x] Expertise in topic
76 | - [x] Shallow bullet points
77 | - [x] Deep information hierarchy
78 | - [x] Level of interest
79 | - [x] Relationship
80 | - [x] Can mix and match
81 | - [x] Examples
82 | - [x] Build an outline
83 | - [x] Structure may come with an outline template (API docs)
84 | - [x] List of the ideas you want to communicate
85 | - [x] Evaluate outline based on goal and audience
86 | - [x] Revise outline
87 | - [x] Revising earlier is cheaper
88 | - [x] Turn outline into prose
89 | - [x] Put flesh on the bones
90 | - [x] Muscles: human connection/emotion for strength
91 | - [x] Connective tissue: transitions between ideas
92 | - [x] Not necessarily exposition
93 | - [x] Stories
94 | - [x] Jokes
95 | - [x] Revise
96 | - [x] Evaluate
97 | - [x] Does this unit advance the goal?
98 | - [x] Is it concise?
99 | - [x] Is it clear?
100 | - [x] Is it organized?
101 | - [x] Is it scannable?
102 | - [x] Plan a correction
103 | - [x] Make corrections
104 | - [x] Get feedback
105 | - [x] Types of readers
106 | - [x] Target audience
107 | - [x] Experts
108 | - [x] Friends
109 | - [x] Evaluating feedback
110 | - [x] Readers are always right about their reactions
111 | - [x] Readers may be wrong about the problems and solutions they identify
112 | - [x] Bear in mind what kind of reader this is
113 | - [x] Produce a list of problems to address and good points to keep
114 | - [x] Revise based on feedback
115 | - [x] See previous
116 | - [x] Publish
117 | - [x] May be done at any point (depending on project)
118 | - [x] Can be part of an iterative process
119 | - [x] Tell people about it
120 | - [x] Not the end of revision
121 | - [x] Conclusion
122 | - [x] Abbreviate process as appropriate
123 |
124 | ## Writing Structures
125 |
126 | - [ ] General Structures
127 | - [ ] Inverted Pyramid
128 | - [ ] what it is
129 | - [ ] why it is useful (time saving)
130 | - [ ] high level
131 | - [ ] low level (topic sentences)
132 | - [ ] List
133 | - [ ] Sequence
134 | - [ ] Q & A ?
135 | - [ ] Informational Structures
136 | - [ ] Hierarchy
137 | - [ ] Examples
138 | - [ ] Textbooks
139 | - [ ] API Docs
140 | - [ ] Persuasive structures
141 | - [ ] Objection - response
142 | - [ ] Persuasive version of Q&A
143 | - [ ] Problem - solution
144 | - [ ] Story
145 | - [ ] Syllogism
146 | - [ ] Juxtaposition (attention grabbers)
147 | - [ ] Combine as appropriate
148 | - [ ] Examples
149 |
150 | ## Audience
151 |
152 | - [ ] Aspects of audience
153 | - [ ] Expertise in subject
154 | - [ ] Relationship to you
155 | - [ ] Motivation for reading
156 | - [ ] Emotional state
157 | - [ ] Level of caution/skepticism
158 | - [ ] Common audiences for developers
159 | - [ ] Other developers
160 | - [ ] Somewhat similar outlook on the world
161 | - [ ] Not necessarily the same as you
162 | - [ ] Experience
163 | - [ ] Different technologies
164 | - [ ] Corporate vs startup
165 | - [ ] QA & testers
166 | - [ ] Designers
167 | - [ ] Teammates
168 | - [ ] Non-technical peers
169 | - [ ] Your boss
170 | - [ ] Management
171 | - [ ] Ops/SysAdmin
172 | - [ ] Users
173 | - [ ] Clients
174 | - [ ] Customers
175 |
176 | ## Genres
177 |
178 | - [ ] Genres
179 | - [ ] Email
180 | - [ ] Docs
181 | - [ ] Code Comments
182 | - [ ] Blog posts
183 | - [ ] Chat?
184 | - [ ] Project site
185 | - [ ] Case for new technology
186 | - [ ] Requirements
187 | - [ ] Bug reports
188 | - [ ] Error messages
189 | - [ ] Help articles
190 | - [ ] UI text
191 | - [ ] Commit messages
192 | - [ ] Code review
193 | - [ ] Code?
194 | - [ ] Talks/presentations?
195 |
196 | ## Other Resources
197 |
198 | - [ ] Books
199 | - [ ] The Elements of Style by Strunk & White
200 | - [ ] The Economist Style Guide
201 | - [ ] Steering the Craft by Ursula K. Le Guin
202 | - [ ] On Writing Well by William Zinsser
203 | - [ ] Writing That Works by Ogilvy?
204 | - [ ] Team Geek?
205 | - [ ] Applications & Tools
206 | - [ ] Workflowy
207 | - [ ] Writeroom
208 | - [ ] Writemonkey
209 | - [ ] IA Writer
210 | - [ ] Hemingway?
211 | - [ ] write-good npm library?
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "spacebook",
3 | "version": "1.0.0",
4 | "description": "A simple site generator based on Eleventy, Tailwind 2.0, and Alpine.js",
5 | "scripts": {
6 | "start": "eleventy --serve & postcss styles/tailwind.css --o _tmp/style.css --watch",
7 | "build": "ELEVENTY_PRODUCTION=true eleventy && NODE_ENV=production postcss styles/tailwind.css --o _site/style.css && ./node_modules/.bin/cleancss -o _site/style.css _site/style.css",
8 | "watch": "npx eleventy --watch",
9 | "debug": "DEBUG=* npx eleventy"
10 | },
11 | "repository": {
12 | "type": "git",
13 | "url": "git+https://github.com/broeker/spacebook.git"
14 | },
15 | "author": "Tim Broeker 🔒 Enter a password to unlock!
229 |
252 |
258 |
259 |
--------------------------------------------------------------------------------
/postcss.config.js:
--------------------------------------------------------------------------------
1 | module.exports = {
2 | plugins: [
3 | require(`tailwindcss`)(`./styles/tailwind.config.js`),
4 | require(`autoprefixer`),
5 | ],
6 | };
7 |
--------------------------------------------------------------------------------
/robots.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Robots
3 | permalink: /robots.txt
4 | layout: layouts/robots.njk
5 | ---
6 |
--------------------------------------------------------------------------------
/search-index.json.njk:
--------------------------------------------------------------------------------
1 | ---
2 | permalink: /search-index.json
3 | ---
4 | {{ collections.results | search | dump | safe }}
5 |
6 |
7 |
--------------------------------------------------------------------------------
/styles/tailwind.config.js:
--------------------------------------------------------------------------------
1 | const autoprefixer = require('autoprefixer');
2 |
3 | module.exports = {
4 | important: true,
5 | future: {
6 | removeDeprecatedGapUtilities: true,
7 | purgeLayersByDefault: true,
8 | },
9 | purge: {
10 | enabled: true,
11 | content: ["_site/**/*.html"],
12 | options: {
13 | safelist: [],
14 | },
15 | },
16 | darkMode: 'class',
17 | theme: {
18 | container: {
19 | center: true,
20 | },
21 | extend: {
22 | typography: {
23 | DEFAULT: {
24 | css: {
25 | maxWidth: '100%',
26 | a: {
27 | color: '#1D4ED8',
28 | '&:hover': {
29 | color: '#1E3A8A',
30 | },
31 | },
32 | '.prose a.edit, .tag a': {
33 | color: '#333',
34 | 'text-decoration': 'none',
35 | },
36 | 'ul.footer-nav': {
37 | '::before': {
38 | display: 'none',
39 | 'text-decoration': 'none',
40 | }
41 | },
42 | 'ul.contains-task-list': {
43 | '::before': {
44 | display: 'none',
45 | }
46 | },
47 | 'ul.spacelog': {
48 | '::before': {
49 | display: 'none',
50 | }
51 | },
52 | },
53 | },
54 | }
55 | },
56 | },
57 | variants: {},
58 | plugins: [
59 | require('@tailwindcss/typography'),
60 | require('@tailwindcss/forms'),
61 | ],
62 | }
--------------------------------------------------------------------------------
/styles/tailwind.css:
--------------------------------------------------------------------------------
1 | @tailwind base;
2 | @tailwind components;
3 | @tailwind utilities;
4 |
5 | @layer base {
6 |
7 | /* Set up some default image behavior for nicer images */
8 | img {
9 | @apply w-auto shadow-md border-2 border-transparent !important
10 | }
11 | img:hover {
12 | @apply border-2 border-gray-100
13 | }
14 | /* Overrides for Tailwind Typography prose class */
15 | .prose a {
16 | @apply dark:text-gray-400
17 | }
18 | .prose a:hover {
19 | @apply dark:text-gray-500
20 | }
21 | .prose h1, .prose h2, .prose h3, .prose h4, .prose h5, .prose h6 .prose hr, .prose strong {
22 | @apply dark:text-gray-400
23 | }
24 | .prose h2, .prose h3, .prose h4, .prose h5, .prose h6 {
25 | scroll-margin-top: 3.5em;
26 | }
27 | .prose pre code {
28 | @apply overflow-x-auto !important
29 | }
30 | .prose .footer-nav a {
31 | @apply no-underline !important
32 | }
33 | .prose ul.contains-task-list,
34 | .prose ul.spacelog {
35 | @apply list-none -ml-6 !important;
36 | }
37 | .prose ul.contains-task-list .task-list-item,
38 | .prose ul.spacelog {
39 | ::before {
40 | @apply hidden !important;
41 | }
42 | }
43 |
44 | /* Define blockquotes and some standard callout blocks */
45 | blockquote {
46 | @apply rounded-lg p-4 bg-gray-100 dark:bg-gray-500 border-gray-200 border-l-8 dark:border-gray-700;
47 | }
48 | .callout {
49 | @apply px-8 py-4 mb-4 rounded-lg bg-yellow-50;
50 | }
51 | .callout, .callout strong, .callout em {
52 | @apply dark:bg-gray-400 dark:text-gray-900;
53 | }
54 | .callout-blue {
55 | @apply px-8 py-4 mb-4 rounded-lg bg-blue-50;
56 | }
57 | .callout-blue, .callout-blue strong, .callout-blue em {
58 | @apply dark:text-gray-200 dark:bg-blue-900;
59 | }
60 | .callout-pink {
61 | @apply px-8 py-4 mb-4 rounded-lg bg-pink-50;
62 | }
63 | .callout-pink, .callout-pink strong, .callout-pink em {
64 | @apply dark:text-gray-200 dark:bg-pink-900;
65 | }
66 | .callout-green {
67 | @apply px-8 py-4 mb-4 rounded-lg bg-green-50;
68 | }
69 | .callout-green, .callout-green strong, .callout-green em {
70 | @apply dark:text-gray-200 dark:bg-green-900;
71 | }
72 | .warning {
73 | @apply px-8 py-4 mb-4 rounded-lg bg-red-800 text-gray-50;
74 | }
75 | .warning, .warning strong, .warning em {
76 | @apply text-gray-50 dark:bg-red-900 dark:text-gray-200;
77 | }
78 |
79 | /* Overrides for nav/Table of Contents block */
80 | nav ul {
81 | @apply ml-0 text-gray-500;
82 | }
83 | nav ul ul {
84 | @apply ml-6 text-gray-500;
85 | }
86 | nav ul li a {
87 | @apply mb-1 pt-2 pr-4 pb-1 pl-2 w-full block text-gray-500 dark:text-gray-500;
88 | }
89 | nav ul li a:hover {
90 | @apply text-gray-900 dark:text-gray-400;
91 | }
92 | nav ul li a.active {
93 | @apply font-semibold;
94 | }
95 | nav.toc ol li {
96 | @apply pt-2 !important
97 | }
98 | nav.toc ol li li {
99 | @apply pt-2 ml-4
100 | }
101 | nav.toc ol li a {
102 | @apply text-gray-500
103 | }
104 | nav.toc ol li a:hover {
105 | @apply text-gray-900
106 | }
107 | .prose .footer-nav a:hover {
108 | @apply dark:text-gray-400 !important
109 | }
110 |
111 | /* Utilities and misc */
112 | .adjust p img, .adjust img, .adjust p iframe, .adjust iframe, .twitter-tweet {
113 | @apply shadow-md ml-auto mr-auto p-2 !important
114 | }
115 | .adjust p img:hover, .adjust img:hover {
116 | @apply shadow-xl
117 | }
118 | .adjust img.button {
119 | @apply w-auto shadow-none !important
120 | }
121 | .text-align-center {
122 | @apply flex justify-center;
123 | }
124 | .icon-spacer {
125 | width: "24px";
126 | }
127 | input {
128 | @apply dark:text-gray-400
129 | }
130 | }
131 |
132 | blockquote p::before {
133 | content: '' !important;
134 | }
135 |
136 | blockquote p::after {
137 | content: '' !important;
138 | }
139 |
140 | blockquote>p:first-child {
141 | margin-top: 0;
142 | }
143 |
144 | blockquote>p:last-child {
145 | margin-bottom: 0;
146 | }
--------------------------------------------------------------------------------
/uploads/uws2.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/joshuacc/prose-for-programmers/fc0c8a4a093f406d380768aa626615307fabf707/uploads/uws2.png
--------------------------------------------------------------------------------
230 |
251 |
231 |
233 |
234 |
235 |
236 |
250 |