* . *
  • About
  • Advertise
  • Privacy & Policy
  • Contact
Monday, July 7, 2025
Earth-News
  • Home
  • Business
  • Entertainment
    Magicians and Battlebots light up Las Vegas entertainment scene – KSNV

    Magicians and Battlebots Take Las Vegas Entertainment by Storm

    Max-Matching Entertainments & Longhua District form partnership for new entertainment complex – Blooloop

    Max-Matching Entertainments and Longhua District Unite to Launch Thrilling New Entertainment Complex

    Kennedy Publishing, MGA Entertainment Launch Yummiland Magazine – License Global

    Kennedy Publishing, MGA Entertainment Launch Yummiland Magazine – License Global

    MAY HER SOUL REST IN PEACE 🙏 Veteran entertainment columnist and talent manager Lolit Solis has passed away. She was 78 years old. https://tinyurl.com/6kumarkx | LatestChika.com – Facebook

    Beloved Entertainment Icon Lolit Solis Passes Away at 78 – A Life Remembered with Love and Respect 🙏

    Neil Young Plays Rare Full-Band ‘Ambulance Blues’ With The Chrome Hearts – Yahoo

    Neil Young Stuns Fans with Rare Full-Band Performance of ‘Ambulance Blues’ Alongside The Chrome Hearts

    BTS Announce Their Big Return and Yes, They Already Have Some Major Plans in the Works – Yahoo

    BTS Announce Their Big Return and Yes, They Already Have Some Major Plans in the Works – Yahoo

  • General
  • Health
  • News

    Cracking the Code: Why China’s Economic Challenges Aren’t Shaking Markets, Unlike America’s” – Bloomberg

    Trump’s Narrow Window to Spread the Truth About Harris

    Trump’s Narrow Window to Spread the Truth About Harris

    Israel-Gaza war live updates: Hamas leader Ismail Haniyeh assassinated in Iran, group says

    Israel-Gaza war live updates: Hamas leader Ismail Haniyeh assassinated in Iran, group says

    PAP Boss to Niger Delta Youths, Stay Away from the Protest

    PAP Boss to Niger Delta Youths, Stay Away from the Protest

    Court Restricts Protests In Lagos To Freedom, Peace Park

    Court Restricts Protests In Lagos To Freedom, Peace Park

    Fans React to Jazz Jennings’ Inspiring Weight Loss Journey

    Fans React to Jazz Jennings’ Inspiring Weight Loss Journey

    Trending Tags

    • Trump Inauguration
    • United Stated
    • White House
    • Market Stories
    • Election Results
  • Science
  • Sports
  • Technology
    Column: Teach kupuna new technology skills – Honolulu Star-Advertiser

    Empowering Kupuna: Unlocking New Technology Skills for a Connected Future

    EIFO invests $5 million in D3, the Ukraine-focused defence technology venture fund – sUAS News

    EIFO Pledges $5 Million to Supercharge Ukraine-Focused Defense Technology Fund

    New Technology for Water Efficiency and Working with Mexico on Screwworm – AG INFORMATION NETWORK OF THE WEST

    Revolutionary Water Efficiency Technology and Cross-Border Collaboration to Defeat Screwworm

    Environmental cognitive distance, R&D capability distance, and supply chain green technology innovation – Nature

    Bridging Gaps: How Environmental and R&D Differences Drive Green Technology Innovation in Supply Chains

    LG Innotek CEO Moon Hyuksoo: “Our Next-gen Substrate Technology Will Change the Industry Paradigm” – TechPowerUp

    LG Innotek CEO Moon Hyuksoo: “Our Next-Gen Substrate Technology Will Revolutionize the Industry” Revolutionizing the Future: LG Innotek’s CEO Unveils Game-Changing Next-Gen Substrate Technology

    Inspira Technologies Secures Landmark $22.5M Deal: Major Revenue Breakthrough After FDA Clearance – Stock Titan

    Inspira Technologies Secures Landmark $22.5M Deal: Major Revenue Breakthrough After FDA Clearance – Stock Titan

    Trending Tags

    • Nintendo Switch
    • CES 2017
    • Playstation 4 Pro
    • Mark Zuckerberg
No Result
View All Result
  • Home
  • Business
  • Entertainment
    Magicians and Battlebots light up Las Vegas entertainment scene – KSNV

    Magicians and Battlebots Take Las Vegas Entertainment by Storm

    Max-Matching Entertainments & Longhua District form partnership for new entertainment complex – Blooloop

    Max-Matching Entertainments and Longhua District Unite to Launch Thrilling New Entertainment Complex

    Kennedy Publishing, MGA Entertainment Launch Yummiland Magazine – License Global

    Kennedy Publishing, MGA Entertainment Launch Yummiland Magazine – License Global

    MAY HER SOUL REST IN PEACE 🙏 Veteran entertainment columnist and talent manager Lolit Solis has passed away. She was 78 years old. https://tinyurl.com/6kumarkx | LatestChika.com – Facebook

    Beloved Entertainment Icon Lolit Solis Passes Away at 78 – A Life Remembered with Love and Respect 🙏

    Neil Young Plays Rare Full-Band ‘Ambulance Blues’ With The Chrome Hearts – Yahoo

    Neil Young Stuns Fans with Rare Full-Band Performance of ‘Ambulance Blues’ Alongside The Chrome Hearts

    BTS Announce Their Big Return and Yes, They Already Have Some Major Plans in the Works – Yahoo

    BTS Announce Their Big Return and Yes, They Already Have Some Major Plans in the Works – Yahoo

  • General
  • Health
  • News

    Cracking the Code: Why China’s Economic Challenges Aren’t Shaking Markets, Unlike America’s” – Bloomberg

    Trump’s Narrow Window to Spread the Truth About Harris

    Trump’s Narrow Window to Spread the Truth About Harris

    Israel-Gaza war live updates: Hamas leader Ismail Haniyeh assassinated in Iran, group says

    Israel-Gaza war live updates: Hamas leader Ismail Haniyeh assassinated in Iran, group says

    PAP Boss to Niger Delta Youths, Stay Away from the Protest

    PAP Boss to Niger Delta Youths, Stay Away from the Protest

    Court Restricts Protests In Lagos To Freedom, Peace Park

    Court Restricts Protests In Lagos To Freedom, Peace Park

    Fans React to Jazz Jennings’ Inspiring Weight Loss Journey

    Fans React to Jazz Jennings’ Inspiring Weight Loss Journey

    Trending Tags

    • Trump Inauguration
    • United Stated
    • White House
    • Market Stories
    • Election Results
  • Science
  • Sports
  • Technology
    Column: Teach kupuna new technology skills – Honolulu Star-Advertiser

    Empowering Kupuna: Unlocking New Technology Skills for a Connected Future

    EIFO invests $5 million in D3, the Ukraine-focused defence technology venture fund – sUAS News

    EIFO Pledges $5 Million to Supercharge Ukraine-Focused Defense Technology Fund

    New Technology for Water Efficiency and Working with Mexico on Screwworm – AG INFORMATION NETWORK OF THE WEST

    Revolutionary Water Efficiency Technology and Cross-Border Collaboration to Defeat Screwworm

    Environmental cognitive distance, R&D capability distance, and supply chain green technology innovation – Nature

    Bridging Gaps: How Environmental and R&D Differences Drive Green Technology Innovation in Supply Chains

    LG Innotek CEO Moon Hyuksoo: “Our Next-gen Substrate Technology Will Change the Industry Paradigm” – TechPowerUp

    LG Innotek CEO Moon Hyuksoo: “Our Next-Gen Substrate Technology Will Revolutionize the Industry” Revolutionizing the Future: LG Innotek’s CEO Unveils Game-Changing Next-Gen Substrate Technology

    Inspira Technologies Secures Landmark $22.5M Deal: Major Revenue Breakthrough After FDA Clearance – Stock Titan

    Inspira Technologies Secures Landmark $22.5M Deal: Major Revenue Breakthrough After FDA Clearance – Stock Titan

    Trending Tags

    • Nintendo Switch
    • CES 2017
    • Playstation 4 Pro
    • Mark Zuckerberg
No Result
View All Result
Earth-News
No Result
View All Result
Home Technology

Docs Deserve More Respect

December 28, 2023
in Technology
Docs Deserve More Respect
Share on FacebookShare on Twitter

I’ve been doing technical writing of one sort or another since 1999, when I was doing QA for Altec Lansing’s R&D branch in Kfar Saba in Israel. Back then we would put out innovative, new audio related devices like (gasp) USB audio devices that worked on Windows ME and 2000. They were buggy and setting them up wasn’t the straightforward thing that it is today.

We needed docs.

We had some hoops that users had to jump through, and we needed a way to document what they were, what the edge cases were, and how to diagnose and fix all of that stuff. It needed to be nicely packaged, cleanly formatted, and accessible to users who installed our helper application. I found Robohelp, which created standard help applications, which could be added to our install.

During our QA process we would identify the issues, document what we thought was salient, and organize it into the help file that was bundled with the device. I was 19 at the time, and I had zero experience with this stuff, and it was an immensely naive process. But, it just felt like the right thing to do for our users, and my manager didn’t explicitly tell me not to.

It’s been 24 years, and since then I’ve done documentation for a bunch of projects. The scale has grown, and the way that I look at those types of projects has substantially changed.

I have some thoughts about what makes for good docs and I’d love to share them with you if you’re interested.

Core Concepts

Id like to start with a set of more concrete rules that I believe are critical to a documentation product’s success.

Docs should use small words to describe big ideas – so don’t use flourishy words or complex sentences to describe what can be said in simpler terms. You will lose users along the way and it isn’t worth your writer’s ego.

Docs should tell a story when you can – because a personal, relatable set of tasks that tell a tale will be more engaging and memorable for your user than an abstract set of instructions.

Docs should be searchable – because seriously: this is a no-brainer. If your docs are not easy to find stuff in, your users won’t find what they need.

Docs are almost always part of a larger strategy – and this is especially true when it comes to software products. This touches on the larger topic of developer advocacy, but in short: your docs should be supported by video tutorials, real use examples, and live technical support.

Docs should be tested – because you may be sure that everything is right, but without real users, like with any other product, you won’t know for certain. Test it and test it again.

Holistic docs are well-designed Products

When you learn a new programming language, concepts and ideas from that language flow into your bag of problem solving tricks. It makes you into a better software developer and at the end of the day, you make better software because you are more aware and capable.

My career has been a complicated one, and included a lot of software product design, software development, technical support, and developer advocacy. Each discipline has influenced how I think and approach the others.

When I approach a Technical Writing project, it’s with this broad view of what it is that a user is going to need. I think that’s the right way to think about docs: holistically. Docs aren’t a well-defined thing and to make good ones you have to be flexible.

To me, that means you have to think about your users from as many angles as possible. You can’t take anything for granted or you’re going to let some group of users down in a way that will negatively impact your brand, your product, or your business in a way that is hard to come back from.

Your docs are very often a make-it-or-break-it experience for your users.

If you did a good job, your users will use your product successfully, and become champions of your brand. If you don’t, they will likely never use your product again because your docs left a bad taste in their minds. They will also let others know. Good marketing starts here, so keep that in mind.

Making good docs

Making good docs simply means that you must approach your docs creation as you would any other product process.

You need to:

Know why you are creating your docs

Know who your target audience is

Know what their pain points are

Improve your docs over time

Let’s take a closer look at each of these.

Knowing the why of your docs is often a really straightforward question and answer set on its surface. You are creating docs because if you don’t, users will fall through the cracks and fail to use your product. At a deeper level there is a specific answer for your use-case. Have a developer tool? That’s one answer set. Have a retail design tool? Have an Accounting SaaS product? Have an automatic coffee maker? These are all separate answer sets.

The form of your docs is described by who will use it. Is it online? Is it bundled with an app? Is it printed? Every user base will need something else and you have to be clear from the get-go who they are.

Your job is to figure out what is hard for each of your users, and craft your docs around funneling them through informative content that solves for their specific problem.

Most importantly, you have know that you probably aren’t going to get it right the first time. That means that your docs need to be maintained and updated as your products grow and change over time. Hopefully, this is done within some framework which allows easy communication with those users you are trying to help. You have to talk to your users, listen to their needs, and try to use your docs to make their experience using your product a better one.

Your docs are an integral part of your success

I’ll sum up by simply underscoring how critically important docs are. Without them, your users are on their own and must fend for themselves.

This will always mean fewer success cases, poorer views of your product within your ecosystem, more unhappy developers or users, and a negative impact on your brand or company.

Docs are a serious sub-product in their own right, are an investment, and must be part of your wider product strategy.

>>> Read full article>>>
Copyright for syndicated content belongs to the linked Source : Hacker News – https://www.ramijames.com/thoughts/docs-deserve-more-respect

Tags: deserveRespecttechnology
Previous Post

Jerry (YC S17) Is Hiring PMs, Engineers, Data Roles (Remote)

Next Post

Book list for streetfighting computer scientists

How New DNA Science Could Help More Families of the Missing – The New York Times

How New DNA Science Could Help More Families of the Missing – The New York Times

July 7, 2025
Letter | Dismissing science comes at a cost – thegazette.com

The High Cost of Ignoring Science

July 7, 2025
Hyatt Pushes Lifestyle Brands Into Asia Pacific Region – Luxury Travel Advisor

Hyatt Pushes Lifestyle Brands Into Asia Pacific Region – Luxury Travel Advisor

July 7, 2025
Kylian Mbappé’s stunning bicycle kick propels Real Madrid to win over Borussia Dortmund, and Club World Cup semifinals – CNN

Kylian Mbappé’s Spectacular Bicycle Kick Secures Real Madrid’s Victory Over Borussia Dortmund and Spot in Club World Cup Semifinals

July 7, 2025
Inside Iran’s war economy – The Economist

Inside the Secret Power Struggles Fueling Iran’s War Economy

July 7, 2025

Santa Cruz Shakespeare Launches Exciting New Monday Night Series

July 7, 2025
When it comes to vaccines, how are pediatricians restoring trust? – NPR

How Pediatricians Are Rebuilding Trust in Vaccines for Children

July 7, 2025
The battle to sway voters over Trump’s ‘big, beautiful bill’ begins – CNN

The battle to sway voters over Trump’s ‘big, beautiful bill’ begins – CNN

July 7, 2025
Column: Teach kupuna new technology skills – Honolulu Star-Advertiser

Empowering Kupuna: Unlocking New Technology Skills for a Connected Future

July 6, 2025
Ben Shelton’s sister booed by Wimbledon crowd when job revealed – Yahoo Sports

Wimbledon Crowd Booes Ben Shelton’s Sister Following Shocking Job Reveal

July 6, 2025

Categories

Archives

July 2025
MTWTFSS
 123456
78910111213
14151617181920
21222324252627
28293031 
« Jun    
Earth-News.info

The Earth News is an independent English-language daily published Website from all around the World News

Browse by Category

  • Business (20,132)
  • Ecology (707)
  • Economy (733)
  • Entertainment (21,621)
  • General (15,749)
  • Health (9,771)
  • Lifestyle (738)
  • News (22,149)
  • People (734)
  • Politics (742)
  • Science (15,950)
  • Sports (21,232)
  • Technology (15,717)
  • World (714)

Recent News

How New DNA Science Could Help More Families of the Missing – The New York Times

How New DNA Science Could Help More Families of the Missing – The New York Times

July 7, 2025
Letter | Dismissing science comes at a cost – thegazette.com

The High Cost of Ignoring Science

July 7, 2025
  • About
  • Advertise
  • Privacy & Policy
  • Contact

© 2023 earth-news.info

No Result
View All Result

© 2023 earth-news.info

No Result
View All Result

© 2023 earth-news.info

Go to mobile version