• About
  • Disclaimer
  • Privacy Policy
  • Contact Us
Monday, May 16, 2022
Tech Fashion Web
Advertisement Banner
  • Home
  • Fashion
    • Footwear
    • Culture
  • Technology
    • Tech Solution
    • Website Design
    • Cyber Security
    • Software
  • Business
  • Digital Marketing
    • SEO
    • Social Media
  • Travel
  • Entertainment
    • Music
    • Celebrity
  • Health
    • Food
  • lifestyle
    • Home
  • More
    • Gaming
    • Gadgets
    • Education
    • Electronics
    • Gadgets
    • Reviews
    • Law
No Result
View All Result
  • Home
  • Fashion
    • Footwear
    • Culture
  • Technology
    • Tech Solution
    • Website Design
    • Cyber Security
    • Software
  • Business
  • Digital Marketing
    • SEO
    • Social Media
  • Travel
  • Entertainment
    • Music
    • Celebrity
  • Health
    • Food
  • lifestyle
    • Home
  • More
    • Gaming
    • Gadgets
    • Education
    • Electronics
    • Gadgets
    • Reviews
    • Law
No Result
View All Result
Tech Fashion web
No Result
View All Result
Home Technology

The state of documentation and why it’s failing IT and users

by Tech Fashion
May 9, 2022
in Technology
0
325
SHARES
2.5k
VIEWS
Share on FacebookShare on Twitter


The state of the project documentation is in disarray and the impact it has on users, administrators and developers is growing every day. Jack Wallen has suggestions to prevent deterioration of the documentation.

Image: Adobe Stock/greenbutterfly

Because of what I do, official documentation is something I depend on on a daily basis. Since most of my writing is tutorials, I look to that documentation as a standard that guides me. Without that documentation, I’d be left to figure everything out. In some cases, that’s not so bad. But in some cases, official documentation is an absolute necessity, so I can turn a rather challenging task into something almost anyone can handle.

SEE: Hiring Kit: Python Developer (Tech Republic Premium)

The point is that not all documentation is created equal. And if there’s one thing I’ve learned over the past five years or so, it’s that relying on official documentation is like relying on a shoe to make your breakfast.

Simply put, the shoe can’t boil and the documentation will let you down.

That’s a hard blow to many projects (of any size). But anyone who has had to use official documentation understands that the struggle is very real. That official documentation is outdated, broken or missing. To make matters worse, in many cases it’s up to you to figure this out.

Why does documentation fail?

Open Source: Coverage You Must Read

While this may not be your first question (when you come across bad documentation), it’s a necessary one. I’ve found there are a few reasons why community documentation fails. With certain software (like Kubernetes), the projects evolve so quickly that the organizers, collaborators and volunteers can’t keep up. When that happens, the first thing you need to do is get the documentation. This is problematic, especially when a new release breaks features from previous iterations. I can’t tell you how many times I’ve had to resort to the official Kubernetes documentation, only to find it doesn’t work. This has happened so many times that I don’t even bother with the official documents. Instead, I sort out the problem myself, or find a Mastodon or other service where users of the product hang out and may have solved the problem.

Another reason this happens is that a project simply doesn’t have the staff to cover documentation. If so, the documentation starts out very sparse and gradually grows over time. But that won’t help early adopters or those who upgrade once the new release is available.

Yet another reason for this is that project managers make their tool for internal use only, don’t bother writing documentation, and eventually release the software to the public (forget they never wrote documentation in the beginning).

All three of these reasons point to what I call the deterioration of the documentation. Unless the documentation is regularly updated, it deteriorates and becomes (eventually) unusable. This is not a sustainable situation.

Why good documentation is important

Simply put, when documentation deteriorates, users, administrators, and developers struggle to use a product. Or worse, those same people have no choice but to look elsewhere. In some cases, there is nowhere else, so those users have no recourse but to try their best to figure out how to make things work.

SEE: Hiring Kit: Back-end Developer (Tech Republic Premium)

That’s where I regularly find myself – struggling through the process of getting something to work. And it happens all the time. I happen to have the luxury of over 20 years of doing this, so making bad documentation is second nature to me. Unfortunately, that’s not the case with everyone. And when a user, administrator, or developer encounters yet another case of documentation degradation, the frustration that comes with it can be disheartening (especially if management is breathing down your neck to get something going).

This is a particularly important problem with: open source software, where users have no company to contact for support. And because so many open source projects can struggle to attract enough volunteers to keep documentation up to date with the releases, it’s even more obvious.

What can be done about deteriorating documentation?

First, larger projects should place more importance on documentation. This should be an absolute no-brainer. And instead of relying on developers to write the documentation (because developers aren’t always the best at explaining something at the end-user or admin level), those projects should consider hiring a documentation team as a must. Yes, there is a cost, but the impact of documentation that not only works, but is easy to follow and measured in brand loyalty and continued growth.

For smaller projects (which cannot afford or attract a dedicated documentation team), the use of volunteers is a must. But so many smaller projects struggle with this. Not only have they failed to set up the process for creating effective documentation, but they also spend most of their recruiting time finding developers. Those smaller projects should prioritize assembling a team to make sure the documentation is coherent, up-to-date, and just works. Social media is a great way to find such people, but it takes time and effort. The reward for your effort is avoiding documentation degradation and happier users.

Until this happens, users, administrators, and developers will struggle to integrate or use your project. When that happens, those potential users will turn away and look for another project. Can you afford that (and the reputation that comes with such an event)?

It’s been a long time since documentation became as important a project element as code. Until that happens, assume that with every update you release something breaks in your how-to’s, readme’s and docs.

Let’s solve that problem now, not later.

Subscribe to TechRepublic’s How to make technology work on YouTube for all the latest technical advice for business professionals from Jack Wallen.



Source link

Share130Tweet81Share33
Previous Post

Aayush Sharma on his ailing grandfather Pandit Sukh Ram: ‘He fights back bravely…’

Next Post

The baby food supply problem is getting worse

Tech Fashion

Tech Fashion

Related Posts

Technology

TeamViewer vs. Remote Desktop | TechRepublic

by Tech Fashion
May 16, 2022
Technology

After Buffalo Shooting Video Spreads, Social Platforms Face Questions

by Tech Fashion
May 16, 2022
Technology

Gradle vs. Maven: DevOps tools comparison

by Tech Fashion
May 16, 2022
Technology

Work from anywhere seamlessly with this dual laptop monitor and lifetime Mac Microsoft license

by Tech Fashion
May 16, 2022
Next Post

The baby food supply problem is getting worse

Avatar The Way of Water trailer: James Cameron promises a visually stunning family saga, watch video

Leave a Reply Cancel reply

Your email address will not be published. Required fields are marked *

No Result
View All Result

Categories

  • Business (2)
  • Celebrity (10)
  • Culture (8)
  • Education (7)
  • Entertainment (250)
  • Fashion (12)
  • Food (7)
  • Footwear (7)
  • Health (6)
  • Lifestyle (14)
  • Music (6)
  • News (347)
  • Social Media (1)
  • Software (3)
  • Tech Solution (1)
  • Technology (277)
  • Travel (12)
  • Website Design (2)

Recent.

Amber Heard testifies that her role in ‘Aquaman 2’ was reduced

May 16, 2022

TeamViewer vs. Remote Desktop | TechRepublic

May 16, 2022

Estonia’s harsh voice on Ukraine urges Putin not to compromise

May 16, 2022
Tech Fashion Web

We bring you the best Premium WordPress Themes that perfect for news, magazine, personal blog, etc. Check our landing page for details.

Category

  • Business
  • Celebrity
  • Culture
  • Education
  • Entertainment
  • Fashion
  • Food
  • Footwear
  • Health
  • Lifestyle
  • Music
  • News
  • Social Media
  • Software
  • Tech Solution
  • Technology
  • Travel
  • Website Design

Recent Posts

  • Amber Heard testifies that her role in ‘Aquaman 2’ was reduced May 16, 2022
  • TeamViewer vs. Remote Desktop | TechRepublic May 16, 2022
  • Estonia’s harsh voice on Ukraine urges Putin not to compromise May 16, 2022

Contact Us

    © 2021 techfashionweb.com . All rights reserved.

    No Result
    View All Result
    • Home
    • Fashion
      • Footwear
      • Culture
    • Technology
      • Tech Solution
      • Website Design
      • Cyber Security
      • Software
    • Business
    • Digital Marketing
      • SEO
      • Social Media
    • Travel
    • Entertainment
      • Music
      • Celebrity
    • Health
      • Food
    • lifestyle
      • Home
    • More
      • Gaming
      • Gadgets
      • Education
      • Electronics
      • Gadgets
      • Reviews
      • Law

    © 2021 techfashionweb.com . All rights reserved.