Muutke küpsiste eelistusi

Docs for Developers: An Engineers Field Guide to Technical Writing 1st ed. [Pehme köide]

3.98/5 (365 hinnangut Goodreads-ist)
, , , ,
  • Formaat: Paperback / softback, 225 pages, kõrgus x laius: 235x155 mm, kaal: 397 g, 31 Illustrations, black and white; XXV, 225 p. 31 illus., 1 Paperback / softback
  • Ilmumisaeg: 01-Oct-2021
  • Kirjastus: APress
  • ISBN-10: 1484272161
  • ISBN-13: 9781484272169
Teised raamatud teemal:
  • Pehme köide
  • Hind: 53,33 €*
  • * hind on lõplik, st. muud allahindlused enam ei rakendu
  • Tavahind: 62,74 €
  • Säästad 15%
  • Raamatu kohalejõudmiseks kirjastusest kulub orienteeruvalt 2-4 nädalat
  • Kogus:
  • Lisa ostukorvi
  • Tasuta tarne
  • Tellimisaeg 2-4 nädalat
  • Lisa soovinimekirja
Docs for Developers: An Engineers Field Guide to Technical Writing 1st ed.Suurem pilt
  • Formaat: Paperback / softback, 225 pages, kõrgus x laius: 235x155 mm, kaal: 397 g, 31 Illustrations, black and white; XXV, 225 p. 31 illus., 1 Paperback / softback
  • Ilmumisaeg: 01-Oct-2021
  • Kirjastus: APress
  • ISBN-10: 1484272161
  • ISBN-13: 9781484272169
Teised raamatud teemal:
Püsilink: https://www.kriso.ee/db/9781484272169.html
Märksõnad:
Learn to integrate programming with good documentation. This book teaches you the craft of documentation for each step in the software development lifecycle, from understanding your users needs to publishing, measuring, and maintaining useful developer documentation.

Well-documented projects save time for both developers on the project and users of the software. Projects without adequate documentation suffer from poor developer productivity, project scalability, user adoption, and accessibility. In short: bad documentation kills projects. 



Docs for Developers demystifies the process of creating great developer documentation, following a team of software developers as they work to launch a new product. At each step along the way, you learn through examples, templates, and principles how to create, measure, and maintain documentationtools you can adapt to the needs of your own organization.







What You'll Learn











Create friction logs and perform user research to understand your users frustrations Research, draft, and write different kinds of documentation, including READMEs, API documentation, tutorials, conceptual content, and release notes Publish and maintain documentation alongside regular code releases Measure the success of the content you create through analytics and user feedback Organize larger sets of documentation to help users find the right information at the right time





Who This Book Is For 











Ideal for software developers who need to create documentation alongside code, or for technical writers, developer advocates, product managers, and other technical roles that create and contribute to documentation for their products and services.







 
About the Authors xv
Acknowledgments xvii
Foreword xix
Introduction xxiii
Chapter 1 Understanding your audience
1(22)
Corg.ly: One month to launch
1(2)
The curse of knowledge
3(1)
Creating an initial sketch of your users
4(4)
Defining your users' goals
4(2)
Understanding who your users are
6(1)
Outline your users' needs
7(1)
Validate your user understanding
8(6)
Using existing data sources
9(1)
Collecting new data
10(4)
Condensing user research findings
14(5)
User personas
15(1)
User stories
16(1)
User journey maps
17(2)
Creating a friction log
19(2)
Summary
21(2)
Chapter 2 Planning your documentation
23(22)
Corg.ly: Creating a plan
23(1)
Plans and patterns
24(1)
Content types
25(16)
Code comments
25(2)
READMEs
27(2)
Getting started documentation
29(1)
Conceptual documentation
30(1)
Procedural documentation
31(4)
Reference documentation
35(6)
Planning your documentation
41(3)
Summary
44(1)
Chapter 3 Drafting documentation
45(22)
Corg.ly: First drafts
45(1)
Confronting the blank page (or screen)
45(1)
Setting yourself up for writing success
46(3)
Choosing your writing tools
47(1)
Breaking through the blank page
47(1)
Defining your document's title and goal
48(1)
Creating your outline
49(3)
Meeting your reader's expectations
50(1)
Completing your outline
51(1)
Creating your draft
52(5)
Headers
53(1)
Paragraphs
54(1)
Procedures
54(1)
Lists
55(1)
Callouts
56(1)
Writing for skimming
57(3)
State your most important information first
58(1)
Break up large blocks of text
59(1)
Break up long documents
59(1)
Strive for simplicity and clarity
60(1)
Getting unstuck
60(3)
Let go of perfectionism
61(1)
Ask for help
61(1)
Highlight missing content
62(1)
Write out of sequence
62(1)
Change your medium
63(1)
Working from templates
63(2)
Finishing your first draft
65(1)
Summary
66(1)
Chapter 4 Editing documentation
67(16)
Corg.ly: Editing content
67(1)
Editing to meet your user's needs
68(1)
Different approaches to editing
69(6)
Editing for technical accuracy
70(1)
Editing for completeness
71(1)
Editing for structure
72(1)
Editing for clarity and brevity
73(2)
Creating an editing process
75(3)
Reviewing your document first
75(1)
Requesting a peer review
76(1)
Requesting a technical review
77(1)
Receiving and integrating feedback
78(1)
Giving good feedback
79(2)
Summary
81(2)
Chapter 5 Integrating code samples
83(18)
Corg.ly: Showing how it works
83(1)
Using code samples
84(1)
Types of code samples
85(1)
Principles of good code samples
86(9)
Explained
87(3)
Concise
90(2)
Clear
92(1)
Usable (and extensible)
93(1)
Trustworthy
94(1)
Designing code samples
95(1)
Choosing a language
95(1)
Highlighting a range of complexity
95(1)
Presenting your code
96(1)
Tooling for code samples
96(3)
Testing code samples
97(1)
Sandboxing code
98(1)
Autogenerating samples
98(1)
Summary
99(2)
Chapter 6 Adding visual content
101(20)
Corg.ly: Worth a thousand words
101(1)
When words aren't enough
102(1)
Why visual content is hard to create
103(3)
Comprehension
104(1)
Accessibility
105(1)
Performance
106(1)
Using screenshots
106(2)
Common types of diagrams
108(4)
Boxes and arrows
108(2)
Flowcharts
110(1)
Swimlanes
111(1)
Drawing diagrams
112(6)
Start on paper
116(1)
Find a starting point for your reader
116(1)
Use labels
116(1)
Use colors consistently
117(1)
Place the diagram
117(1)
Publishing a diagram
117(1)
Get help with diagrams
117(1)
Creating video content
118(1)
Reviewing visual content
119(1)
Maintaining visual content
120(1)
Summary
120(1)
Chapter 7 Publishing documentation
121(12)
Corg.ly: Ship it!
121(1)
Putting your content out there
122(1)
Building a content release process
123(1)
Creating a publishing timeline
124(5)
Coordinate with code releases
126(1)
Finalize and approve publication
126(2)
Decide how to deliver content
128(1)
Announce your docs
129(1)
Planning for the future
129(1)
Summary
130(3)
Chapter 8 Gathering and integrating feedback
133(14)
Corg.ly: Initial feedback
133(1)
Listening to your users
134(1)
Creating feedback channels
135(6)
Accept feedback directly through documentation pages
136(1)
Monitor support issues
137(1)
Collect document sentiment
138(1)
Create user surveys
139(1)
Create a user council
140(1)
Converting feedback into action
141(4)
Triaging feedback
141(4)
Following up with users
145(1)
Summary
145(2)
Chapter 9 Measuring documentation quality
147(22)
Corg.ly: Tuesday after the launch
147(1)
Is my documentation any good?
148(1)
Understanding documentation quality
148(10)
Functional quality
149(6)
Structural quality
155(3)
How functional and structural quality relate
158(1)
Creating a strategy for analytics
158(6)
Organizational goals and metrics
159(1)
User goals and metrics
160(2)
Documentation goals and metrics
162(2)
Tips for using document metrics
164(2)
Make a plan
164(1)
Establish a baseline
165(1)
Consider context
165(1)
Use clusters of metrics
166(1)
Mix qualitative and quantitative feedback
166(1)
Summary
166(3)
Chapter 10 Organizing documentation
169(18)
Corg.ly: The next release
169(1)
Organizing documentation for your readers
170(1)
Helping your readers find their way
171(8)
Site navigation and organization
172(4)
Landing pages
176(2)
Navigation cues
178(1)
Organizing your documentation
179(5)
Assess your existing content
179(2)
Outline your new information architecture
181(2)
Migrate to your new information architecture
183(1)
Maintaining your information architecture
184(1)
Summary
184(3)
Chapter 11 Maintaining and deprecating documentation
187(14)
Corg.ly: A few releases later
187(1)
Maintaining up-to-date documentation
188(1)
Planning for maintainability
189(4)
Align documentation with release processes
190(2)
Assign document owners
192(1)
Reward document maintenance
193(1)
Automating documentation maintenance
193(3)
Content freshness checks
194(1)
Link checkers
195(1)
Linters
195(1)
Reference doc generators
196(1)
Removing content from your docset
196(3)
Deprecating documentation
197(1)
Deleting documentation
198(1)
Summary
199(2)
Appendix A When to hire an expert
201(4)
Meeting a new set of user needs
202(1)
Increasing support deflections
202(1)
Managing large documentation releases
202(1)
Refactoring an information architecture
202(1)
Internationalization and localization
203(1)
Versioning documentation with software
203(1)
Accepting user contributions to documentation
203(1)
Open-sourcing documentation
204(1)
Appendix B Resources
205(10)
Courses
205(1)
Templates
206(1)
Style guides
207(1)
Automation tools
207(2)
Visual content tools and frameworks
209(1)
Blogs and research
210(1)
Books
211(1)
Communities
212(3)
Bibliography 215(6)
Index 221
Jared Bhatti





Jared is a Staff Technical Writer at Alphabet, and the co-founder of Googles Cloud documentation team. Hes worked for the past 14 years documenting an array of projects at Alphabet, including Kubernetes, App Engine, Adsense, Googles data centers, and Googles environmental sustainability efforts. He currently leads technical documentation at Waymo and mentors several junior writers in the industry.

Sarah Corleissen Sarah (she/her, they/them) began this book as the Lead Technical Writer for the Linux Foundation and ended it as Stripes first Staff Technical Writer. Sarah served as co-chair for Kubernetes documentation from 2017 until 2021, and has worked on developer docs previously at GitHub, Rackspace, and several startups. They enjoy speaking at conferences and love to mentor writers and speakers of all abilities and backgrounds. Heidi Waterhouse

Heidi spent a couple decades at Microsoft, Dell Software, and many, many startups learning to communicate with and for developers. She currently works as a principal developer advocate at LaunchDarkly, but was reassured to find that technical communication is universal across all roles. 

David Nunez

David heads up the technical writing organization at Stripe, where he founded the internal documentation team and wrote for Increment magazine. Before Stripe, he founded and led the technical writing organization at Uber and held a documentation leadership role at Salesforce. Having led teams that have written about cloud, homegrown infrastructure, self-driving trucks, and economic infrastructure, hes studied the many ways that technical documentation can shape the user experience. David also acts as an advisor for several startups in the knowledge platform space.

Jen Lambourne

Jen leads the technical writing and knowledge management discipline at Monzo Bank. Before her foray into fintech, she led a community of documentarians across the UK government as Head of Technical Writing at the Government Digital Service (GDS). Having moved from government to finance, she recognizes shes drawn to creating inclusive and user-centred content in traditionally unfriendly industries. She likes using developer tools to manage docs, demystifying the writing process for engineers, mentoring junior writers, and presenting her adventures in documentation at conferences.