Professional Documents
Culture Documents
Crafting Docs for Success. An End-to-End Approach to Developer Documentation Diana Lakatos full chapter instant download
Crafting Docs for Success. An End-to-End Approach to Developer Documentation Diana Lakatos full chapter instant download
An
End-to-End Approach to Developer
Documentation Diana Lakatos
Visit to download the full and correct content document:
https://ebookmass.com/product/crafting-docs-for-success-an-end-to-end-approach-to-
developer-documentation-diana-lakatos/
More products digital (pdf, epub, mobi) instant
download maybe you interests ...
https://ebookmass.com/product/enterprise-ai-in-the-cloud-a-
practical-guide-to-deploying-end-to-end-machine-learning-and-
chatgpt-solutions-rabi-jay/
https://ebookmass.com/product/tight-end-vegas-aces-the-tight-end-
book-5-lisa-suzanne/
https://ebookmass.com/product/getting-started-with-microsoft-
viva-an-end-user-guide-to-business-transformation-1st-edition-
darce-hess/
https://ebookmass.com/product/exit-path-how-to-win-the-startup-
end-game-touraj-parang/
Believing: Our Thirty-Year Journey to End Gender
Violence Anita Hill
https://ebookmass.com/product/believing-our-thirty-year-journey-
to-end-gender-violence-anita-hill/
https://ebookmass.com/product/wreckonomics-why-its-time-to-end-
the-war-on-everything-ruben-andersson/
https://ebookmass.com/product/the-glitter-end-vivian-conroy-2/
https://ebookmass.com/product/the-glitter-end-vivian-conroy/
https://ebookmass.com/product/end-of-night-ramona-gray/
Design Thinking
Design Thinking is a set of strategic and creative processes and principles
used in the planning and creation of products and solutions to human-
centered design problems.
With design and innovation being two key driving principles, this
series focuses on, but not limited to, the following areas and topics:
• Psychology of Design
• Ergonomic Design
Diana Lakatos
Crafting Docs for Success: An End-to-End Approach to Developer
Documentation
Diana Lakatos
Szeged, Hungary
Chapter 1: Approaches�������������������������������������������������������������������������1
Documentation As a Product���������������������������������������������������������������������������������2
Design Thinking����������������������������������������������������������������������������������������������������4
The Phases of the Design Thinking Process����������������������������������������������������5
Design Thinking in Your Developer Documentation Project�����������������������������7
Docs as Code������������������������������������������������������������������������������������������������������10
Docs as Code for Developer Documentation�������������������������������������������������11
Docs-as-Code Benefits����������������������������������������������������������������������������������12
Community-Driven Documentation���������������������������������������������������������������������14
Content First�������������������������������������������������������������������������������������������������������15
Topic-Based Authoring and DITA�������������������������������������������������������������������������16
Summary������������������������������������������������������������������������������������������������������������18
Chapter 2: Foundations����������������������������������������������������������������������21
Project Discovery������������������������������������������������������������������������������������������������21
User Research�����������������������������������������������������������������������������������������������������23
User Research Methodologies�����������������������������������������������������������������������25
Competitive Analysis�������������������������������������������������������������������������������������������27
v
Table of Contents
Target Audience��������������������������������������������������������������������������������������������������29
Developers�����������������������������������������������������������������������������������������������������29
Other Target Audience Segments������������������������������������������������������������������32
User Interviews���������������������������������������������������������������������������������������������������34
Personas�������������������������������������������������������������������������������������������������������������35
Content Inventory������������������������������������������������������������������������������������������������39
Sitemap���������������������������������������������������������������������������������������������������������������42
Card Sorting Exercise������������������������������������������������������������������������������������42
Persona-Based Content Prioritization�����������������������������������������������������������������47
Summary������������������������������������������������������������������������������������������������������������49
vi
Table of Contents
Format�����������������������������������������������������������������������������������������������������������76
Images�����������������������������������������������������������������������������������������������������������76
Videos������������������������������������������������������������������������������������������������������������77
Accessibility and Inclusive Language������������������������������������������������������������78
Templates������������������������������������������������������������������������������������������������������78
Documentation Style Guide Checklist������������������������������������������������������������90
Changelogs and Release Notes��������������������������������������������������������������������������91
Use Cases�����������������������������������������������������������������������������������������������������������93
Legal Copy����������������������������������������������������������������������������������������������������������95
Developer Onboarding����������������������������������������������������������������������������������������96
Search Engine Optimization��������������������������������������������������������������������������������97
Summary������������������������������������������������������������������������������������������������������������98
Chapter 5: Implementation�����������������������������������������������������������������99
Wireframes����������������������������������������������������������������������������������������������������������99
Layouts and Design�������������������������������������������������������������������������������������������102
Technical Implementation���������������������������������������������������������������������������������106
Git����������������������������������������������������������������������������������������������������������������108
Static Site Generators����������������������������������������������������������������������������������109
API Documentation Generators��������������������������������������������������������������������113
platformOS��������������������������������������������������������������������������������������������������115
Automation��������������������������������������������������������������������������������������������������116
Summary����������������������������������������������������������������������������������������������������������119
Chapter 6: Community����������������������������������������������������������������������121
Contribution������������������������������������������������������������������������������������������������������121
Ways to Contribute��������������������������������������������������������������������������������������122
Contributor Experience��������������������������������������������������������������������������������130
vii
Table of Contents
Communication�������������������������������������������������������������������������������������������������131
Community��������������������������������������������������������������������������������������������������������133
Summary����������������������������������������������������������������������������������������������������������135
Chapter 8: Sustainability������������������������������������������������������������������155
What Would a Sustainable Internet Look Like?�������������������������������������������������156
What Makes a Website Sustainable?����������������������������������������������������������������157
Hosting��������������������������������������������������������������������������������������������������������160
Performance������������������������������������������������������������������������������������������������161
Image Management�������������������������������������������������������������������������������������163
Video Management��������������������������������������������������������������������������������������164
Fonts������������������������������������������������������������������������������������������������������������165
Web Caching������������������������������������������������������������������������������������������������166
User Experience������������������������������������������������������������������������������������������166
Content Management����������������������������������������������������������������������������������166
Search Engine Optimization������������������������������������������������������������������������167
Third-Party Tools������������������������������������������������������������������������������������������167
Summary����������������������������������������������������������������������������������������������������������168
viii
Table of Contents
Chapter 9: Team��������������������������������������������������������������������������������169
The Members of Your Documentation Team�����������������������������������������������������169
Documentation Lead�����������������������������������������������������������������������������������170
Technical Writer/Editor��������������������������������������������������������������������������������171
UX Researcher���������������������������������������������������������������������������������������������172
Information Architect�����������������������������������������������������������������������������������173
Interaction Designer������������������������������������������������������������������������������������173
UX Writer������������������������������������������������������������������������������������������������������174
UX Designer�������������������������������������������������������������������������������������������������174
UI Designer��������������������������������������������������������������������������������������������������174
Developers���������������������������������������������������������������������������������������������������175
Quality Assurance����������������������������������������������������������������������������������������176
Automation and DocOps������������������������������������������������������������������������������176
Project Management�����������������������������������������������������������������������������������176
Educating Your Team Members�������������������������������������������������������������������������177
Summary����������������������������������������������������������������������������������������������������������180
Index�������������������������������������������������������������������������������������������������207
ix
About the Author
Diana Lakatos is an experienced Developer
Documentation Specialist dedicated to
creating high-quality resources for developers.
She has played an instrumental role in the
development of the multiple award-winning
platformOS Developer Portal and manages
all phases of the editorial workflow, creates
templates, incorporates best practices, and
writes, edits, and reviews content. She spoke
about various aspects of building world-class
developer docs at conferences like Write the Docs, tcworld, DevRelCon,
and API The Docs.
xi
About the Technical Reviewer
Anne Gentle is the Developer Experience
Manager for developer advocacy, API
documentation, and API quality assessments
within developer relations and strategy
at Cisco. With her teams of experts, she is
responsible for developer tools for API design,
developer documentation, and developer
tutorials, including infrastructure integration
and interactivity. Before her time at Cisco,
Anne led large open-source communities in API documentation efforts
and blazed trails supporting women in technology through internship
programs like Outreachy. Anne was a Principal Engineer at Rackspace,
serving on the OpenStack Technical Committee while advocating for cloud
API users.
Anne wrote a book, Docs Like Code, to demonstrate developer
tools and workflows like GitHub and automated publishing and code
integration applied in the technical writing world. Anne proudly serves on
the Workforce Advisory Committee at Austin Community College, pushing
the field toward future API and developer documentation opportunities. In
collaboration with the Inclusive Future Action Office at Cisco, Anne works
with engineering teams to eliminate biased language in code and content.
xiii
Acknowledgments
I’d like to extend my appreciation to everyone who has been a part of this
journey and contributed to the creation of this book.
First and foremost, I owe a heartfelt thank you to my family. Your love
and support mean the world to me.
I am immensely thankful to Gyöngy Gora, a remarkably talented
Senior UI Designer and Design System Specialist, for creating the visually
engaging illustrations in the book.
I wish to express my gratitude to Kata Nagygyörgy, whose expertise in
UX research has significantly enriched the content of this book.
Special thanks go to Péter Almási, a seasoned Senior Frontend
Engineer, whose extensive experience greatly informed the technical
aspects of the book.
A tremendous thank you goes to Anne Gentle, who meticulously
reviewed the content of the book. Your precision and profound knowledge
in the field have played a crucial role in ensuring the accuracy of this work.
I want to express my thanks to the platformOS team, with whom I had
the privilege of building the platformOS Documentation. The collective
knowledge and experiences we amassed have greatly shaped this book.
A big thank you to the Write the Docs community for your ongoing
support, shared wisdom, and inspiring passion for creating quality
documentation.
Finally, I want to express my appreciation to you, the readers. I
hope the insights, strategies, and experiences shared within these pages
contribute to your knowledge and success in the field of developer
documentation.
xv
Introduction
In 2018, I joined the platformOS team to establish documentation
processes and build the developer portal for their model-based application
development platform, targeting front-end developers and site builders.
We could essentially start from scratch: some content already existed
(files in a GitHub repository written by developers), but there was no
documentation site. It was the perfect time for me to join, as it provided us
with the opportunity to develop a solid foundation to build upon.
As you can probably imagine, this felt like an overwhelming
undertaking. I was the sole writer and documentation specialist in a team
of 25 people, mostly developers, all working remotely. As our first move,
we invited a UX researcher – from Chapter 2, “Foundations,” onward, you’ll
understand why her involvement was essential. We used all the resources
we could find: our previous experience working on developer portals,
articles, courses, webinars, conference talks. There were a lot of excellent
learning materials scattered all over the Internet (which I will share with
you), but we had to figure out what to use and how to apply it to our project
on our own. It was a lengthy process, and although it was overall a very
rewarding experience, having a framework to follow and adjust as needed
would have been greatly helpful. That’s what this book aims to provide:
a blueprint for building successful developer documentation, where I
share our experience, along with practical, usable templates, workflows,
and tools.
We’re still a small remote team, but now we have a world-class
developer portal that has become one of the most important assets for
our community and business. Here’s how you can craft docs for developer
success, too.
xvii
CHAPTER 1
Approaches
Even if you are starting something from scratch, you probably don’t have
to start from zero: there is a good chance that other people have worked
on something similar before, or came up with processes and solutions that
you can apply to your project. The challenge is finding the approaches that
would work for you.
This chapter explains approaches you can follow, why and how you
can use them, and why they can be beneficial for any documentation
project:
• Documentation as a product
• Design Thinking
• Docs as Code
• Community-driven documentation
• Content First
Documentation As a Product
Your developer documentation is naturally linked to the product it
documents, but considering the crucial role it plays in the adoption, use,
and marketing of your product, it should be considered a product in its
own right.
Your developer documentation can become your most important asset
in developer relations that fulfills a wide range of different functions:
• It should provide all the necessary information for
developers to start working with your product as the
key ingredient in your onboarding.
2
Chapter 1 Approaches
Tip You can use the preceding list as an outline for collecting your
arguments if you need to convince stakeholders about the value
developer documentation can bring to the business.
3
Chapter 1 Approaches
You and your company have to see your docs for what they really are: a
complex product that needs attention, time, resources, and funding to be
successful.
Design Thinking
Design Thinking is a human-centered iterative design process that consists
of predefined steps you can follow to understand your users, reevaluate
your assumptions, define or redefine problems, and create solution
prototypes that you can test.
The origins of Design Thinking go back to the development of
psychological studies on creativity and creativity techniques in the 1940s
and 1950s, and the approach has been refined ever since to arrive at a
state where it’s now widely considered to be a generalizable approach to
technical and social innovation.
Note If you would like to learn more about the interesting history
and other aspects of Design Thinking, I suggest you read The Design
Thinking Playbook1 by Michael Lewrick, Patrick Link, and Larry
Leifer; select some books you’re interested in from the Apress Design
Thinking series2; or delve deeper into online articles on the topic, for
example, by the Interaction Design Foundation3.
1
h ttps://www.amazon.com/Design-Thinking-Playbook-Transformation-
Businesses/dp/1119467470
2
https://www.springer.com/series/15933
3
https://www.interaction-design.org/
4
Chapter 1 Approaches
• Phase 1: Empathize
• Phase 2: Define
• Phase 3: Ideate
5
Chapter 1 Approaches
• Phase 4: Prototype
• Phase 5: Test
6
Another random document with
no related content on Scribd:
said to have made it a by-law to himself to use only four colours in
painting: probably Apelles found his advantage in that restraint, or
he would not have imposed it on his pallet. But if Zeuxis found that
he, Zeuxis, painted better by using a dozen colours than by confining
himself to four, he would have used a dozen, or he would not have
been Zeuxis.
On careful and thoughtful examination we shall find, that neither
in narrative nor dramatic fiction do great writers differ on the
principles of art in the works which posterity accepts from them as
great—whereas they all differ more or less in technical rules. There is
no great poetic artist, whether in narrative or the drama, who, in his
best works, ever represents a literal truth rather than the idealised
image of a truth—who ever condescends to servile imitations of
nature—who ever prefers the selection of particulars, in the
delineation of character or the conception of fable, to the expression
of generals—who does not aim at large types of mankind rather than
the portraiture of contemporaries—or, at least, wherever he may
have been led to reject these principles, it will be in performances
that are allowed to be beneath him. But merely technical rules are no
sooner laid down by the critics of one age, than they are scornfully
violated by some triumphant genius in the next. Technical rules have
their value for the artist who employs them, and who usually invents
and does not borrow them. Those that he imposes on himself he
seldom communicates to others. They are his secret—they spring
from his peculiarities of taste; and it is the adherence to those rules
which constitutes what we sometimes call his style, but more
properly his manner. It is by such rules, imposed on himself, that
Pope forms his peculiar cæsura, and mostly closes his sense at the
end of a couplet. When this form of verse becomes trite and
hackneyed, up rises some other poet, who forms by-laws for himself,
perhaps quite the reverse. All that we should then ask of him is
success: if his by-laws enable him to make as good a verse as Pope’s
in another way, we should be satisfied; if not—not. One main use in
technical rules to an author, if imposed on himself, or freely assented
to by himself, is this—the interposition of some wholesome
impediment to the over-facility which otherwise every writer
acquires by practice. And as this over-facility is naturally more apt to
be contracted in prose than in verse, and in the looseness or length of
the novel or romance, than in any other more terse and systematic
form of imaginative fiction—so I think it a wise precaution in every
prolific novelist to seek rather to multiply, than emancipate himself
from, the wholesome restraints of rules; provided always that such
rules are the natural growth of his own mind, and confirmed by his
own experience of their good effect on his productions. For if Art be
not the imitator of Nature, it is still less the copyist of Art. Its base is
in the study of Nature—not to imitate, but first to select, and then to
combine, from Nature those materials into which the artist can
breathe his own vivifying idea; and as the base of Art is in the study
of Nature, so its polish and ornament must be sought by every artist
in the study of those images which the artists before him have
already selected, combined, and vivified; not, in such study, to
reproduce a whole that represents another man’s mind, and can no
more be born again than can the man who created it; but again to
select, to separate, to recombine—to go through the same process in
the contemplation of Art which he employed in the contemplation of
Nature; profiting by all details, but grouping them anew by his own
mode of generalisation, and only availing himself of the minds of
others for the purpose of rendering more full and complete the
realisation of that idea of truth or beauty which has its conception in
his own mind. For that can be neither a work of art (in the æsthetic
sense of the word) nor a work of genius in any sense of the word,
which does not do a something that, as a whole, has never been done
before; which no other living man could have done; and which never,
to the end of time, can be done again—no matter how immeasurably
better may be the other things which other men may do. ‘Ivanhoe’
and ‘Childe Harold’ were produced but the other day; yet already it
has become as impossible to reproduce an ‘Ivanhoe’ or a ‘Childe
Harold’ as to reproduce an ‘Iliad.’ A better historical romance than
‘Ivanhoe,’ or a better contemplative poem than ‘Childe Harold,’ may
be written some day or other; but, in order to be better, it must be
totally different. The more a writer is imitated the less he can be
reproduced. No one of our poets has been so imitated as Pope, not
because he is our greatest or our most fascinating poet, but because
he is the one most easily imitated by a good versifier. But is there a
second Pope, or will there be a second Pope, if our language last ten
thousand years longer?
THE LIFE OF GENERAL SIR HOWARD
DOUGLAS, BART.[3]
“Several days elapsed before the fire subsided, and then it became masked by a
smoke which darkened the whole country. But night proved that it had not burned
out; for showers of flame shot up at intervals, and trees stood glaring in the dark,
while the mingled black and red of the sky seemed its embers overhead. Thus a
week passed, when Sir Howard determined to penetrate the forest, and visit the
different settlements. A friend has described his parting with Lady Douglas and his
daughters, whose pale faces betrayed their emotion, though they forbore to oppose
his design, knowing that nothing would keep him from his duty. But this was not
understood by others, and the gentlemen of the town gathered round his rough
country waggon at the door, and entreated him to wait a few days, pointing to the
mountains of smoke, and declaring that he must be suffocated if he escaped being
burned. He thanked them for their good feeling, grasped their hands, and mounted
the waggon. It dashed off at a gallop, and wondering eyes followed it to the woods,
where it disappeared in the smoke.
“The devastation he met exceeded his worst fears; for the settlements he went to
visit no longer existed. The fire seems to have burst in every quarter at once; for it
broke out at Miramichi the same moment as at Fredericktown, though one
hundred and fifty miles lay between. But here its aspect was even more dreadful,
and its ravages more appalling, as Miramichi stood in the forest completely girt
round except where escape was shut off by the river. Many were in bed when they
heard the alarm; many were first startled by the flames, or were suffocated in their
sleep, leaving no vestige but charred bones; others leaped from roof or window,
and rushed into the forest, not knowing where they went, or took fire in the street,
and blazed up like torches. A number succeeded in gaining the river, and threw
themselves in boats or on planks, and pushed off from the banks, which the fire
had almost reached, and where it presently raged as fiercely as in the town. One
woman was aroused from sleep by the screams of her children, whom she found in
flames, and caught fire herself as she snatched up an infant and ran into the river,
where mother and child perished together. Then came the hurricane, tearing up
burning trees and whirling them aloft, lashing the river and channel to fury, and
snapping the anchors of the ships, which flew before it like chaff, dashing on the
rocks, and covering the waves with wreck. Blazing trees lighted on two large
vessels, and they fired like mines, consuming on the water, which became so hot in
the shallows that large salmon and other fish leaped on shore, and were afterwards
found dead in heaps along the banks of the river. What can be said of such horrors,
combining a conflagration of one thousand miles with storm and shipwreck, and
surprising a solitary community at midnight? Happily the greater number
contrived to reach Chatham by the river; but floating corpses showed how many
perished in the attempt, and nearly three hundred lost their lives by fire or
drowning.”
“The following day” (the day after one of these mishaps) “brought Captain
Wallace to dine with the Governor, and it came out that he had been hearing tales
about his Excellency which he did not consider to his advantage, for he suddenly
asked him if he had not once been shipwrecked. Sir Howard replied by telling the
story, and the captain’s face became longer as he proceeded, though he made no
remark till the close. He then observed that his regard for him was very great, and
he valued their interchange of hospitality in port and ashore, but should never like
to take him to sea again; for he had been twenty years afloat without mishap,
except on the two occasions when they had been together; and he should now look
upon his appearance in his ship as a passenger as a very bad omen indeed.”
On both occasions the ship had struck for lack of proper beacons,
and Sir Howard at once applied the remedy. He caused lighthouses
to be built where they were most required; and in order to improve
the internal communications of the province, he made roads, and
proposed a plan for connecting by a canal the Bay of Fundy with the
Gulf of St Lawrence. Meanwhile he was not neglectful of the
intellectual wants of the colonists, as yet very imperfectly attended
to. He founded, endowed, and, after a good deal of opposition,
obtained a charter for the University of Fredericktown, of which, in
1829, he became the first Chancellor, giving at the same time his own
name to the College. These were works of peace; and he was equally
careful in guarding against the chances of war. The treaty of 1783 had
left the boundary-line between Great Britain and the United States
very imperfectly defined; and as the inhabitants of the latter country
increased in number, they began to encroach on the territories of the
former. A good many squatters had forced themselves into New
Brunswick, and been driven away, till at last a person named Baker,
bolder than the rest, took possession of an outlying portion of land,
and hoisted the American standard. The proceeding was much
approved by the Government of Maine, and strong parties of the
militia were turned out in anticipation of a collision with the garrison
of Fredericktown.
Sir Howard Douglas, however, knew better than to precipitate
hostilities. He contented himself with sending a civil message to
Baker, requesting him to withdraw; and when no attention was paid
to it, he gave such orders to the troops as would bring them to the
frontier in a few hours should their presence be required. This done,
a parish constable was desired to perform his duty; and the man,
coming upon Baker without any fuss or parade, cut down the flag-
staff, seized the squatter, and carried him off in a waggon to the
capital of the province. All Maine was thrown into a ferment. The
Governor threatened, and demanded that Baker should be set at
liberty. Sir Howard refused so much as to see the messenger
intrusted with this demand, justly alleging that he could hold
communication on such subjects only with the Central Government
at Washington. The result was, that Baker, being put upon his trial,
was found guilty, and sentenced to pay a fine; which fine, after an
enormous amount of bluster, was duly paid. For his firm yet
judicious conduct throughout this awkward affair Sir Howard
received the approbation of the Home Government, becoming at the
same time more than ever an object of enthusiastic admiration to the
people whom he governed.
While approving all that their representative had done, the British
Government saw that it would be impossible with safety to leave the
boundary question longer unsettled. Arrangements were accordingly
made with the United States for referring the points at issue to
arbitration; and the King of the Netherlands being accepted as
arbitrator, Sir Howard was requested to return to Europe, and to
watch proceedings. The King’s decision gave, however, little
satisfaction to either party. England, indeed, would have acquiesced
in it, though feeling herself wronged; but America failed to get all
that she coveted, and refused to be bound. It remained for her, by
sharp practice at a future period, to gain her end; and for England,
under the management of Lord Ashburton and Sir Robert Peel, to be
made a fool of. The part played by Sir Howard Douglas during the
progress of this negotiation was every way worthy of his high
reputation; but that which strikes us most is the sagacity with which,
so early as 1828, he foretold events in the States themselves, which
have since come to pass. In a paper addressed to the Secretary for the
Colonies, which points out endless grounds of quarrel between the
Federal Government and the Governments of the several States, he
thus expresses himself:—
“Here we may see the manner in which the Union will be dissolved—viz., the
secession of any State which, considering its interest, property, or jurisdiction
menaced, may no longer choose to send deputies to Congress. This is a great defect
in the Bond of Union, which has not, perhaps, been very generally noticed, cloaked
as it is under article 1st, section 5th of the Constitution, which states ‘that where
there are not present, of either House, members sufficient to form a quorum to do
business, a smaller number may be authorised, for the purpose of forming one, to
compel the attendance of absent members.’ But this appears only to be authorised
for the purpose of forming a quorum, and only extends over members actually
sworn in, who, being delegated to Congress by the States they represent, are
subjected to whatever rules of proceeding and penalties each House may provide,
with the concurrence of two-thirds of its members. But there is nothing obligatory