|
Disclosure: While I was in college I spent almost a year in a technical writer position. By the end, I no longer had any hesitation when it came to writing. In the 40 years since, I've written thousands of pages of all kinds of documentation, from formal specifications to user manuals and application help files.
I think this article and most of the responses thus far miss an essential and fundamental property of all writing: knowing who's your audience. You must answer the question: who are you writing this documentation for? As an example, documenting a library's API for use by other developers is very different from documenting that same library for maintenance developers working on the library itself. Both of these differ in turn from user documentation for an application that uses the library. All three cases could conceivably be written by the developer and all three documents are vastly different from each other.
Once you answer the 'audience' question correctly and completely, the kind of information that needs to be in the document should be pretty obvious. Often that will also tell you how the document should be organized, if the items of information should be presented in a particular way or order, and so on. At that point it's a matter of filling in the blanks. Yes, it can be time-consuming but it can also be useful. I've had many times when I've been writing documentation and discovered that the associated software needed a change, just from the different viewpoint when writing vs. coding.
I will freely admit my work experience has left me with little patience when it comes to engineers complaints about writing documentation. Many gripe that it's boring, tedious, or (my favorite) beneath their dignity to be asked to document their work. I've frequently been the brunt of their contempt when I insist on documenting something. In my view, if your code goes anywhere other than the computer directly in front of you, you damned well better be able to document it. Software is complicated and written documentation is often the default (can you imagine verbal documentation for Boost?). For anyone else using it, the perceived value of your code is limited by the documentation you provide.
Software Zen: delete this;
|
|
|
|
|
|
I do tend to preach at times
Software Zen: delete this;
|
|
|
|
|
Sometimes it is necessary to preach
|
|
|
|
|
.....by the time the bugs are fixed they hardly have any life...
Caveat Emptor.
"Progress doesn't come from early risers – progress is made by lazy men looking for easier ways to do things." Lazarus Long
|
|
|
|
|
Research firm Gartner estimates the market for hyperautomation-enabling technologies will reach $596 billion in 2022, up nearly 24% from the $481.6 billion in 2020. Acronyms deemed profitable
|
|
|
|
|
Kent Sharkey wrote: Acronyms deemed profitable Almost the same as last year. But this year will be the year of the AI desktop!
Bastard Programmer from Hell
"If you just follow the bacon Eddy, wherever it leads you, then you won't have to think about politics." -- Some Bell.
|
|
|
|
|
|
Continuing our series on the over 100 API changes in .NET 6, we look at extensions to the LINQ library. These are not the weakest LINQs. Goodbye
|
|
|
|
|
After spending $9 billion combined, Verizon may sell units for $4 billion or so. Have some spare cash? You could be a Yahoo!
I wonder if part of the price for AOL is the warehouse of CDs?
|
|
|
|
|
Kent Sharkey wrote: I wonder if part of the price for AOL is the warehouse of CDs?
LOL!
This explains why they've been so ruthlessly culling stuff like Yahoo Groups. The irony is that, even now, there was and is money to be made with mail lists (and web forum integration). It just needed some investment. It could have been a profit centre; but no, they killed it instead. No surprise they're not doing well.
|
|
|
|
|
And just before any potential sale, they'll have also killed off Yahoo Answers. Like with Groups it had fallen behind the competition due to neglect, but with some work it could become a viable competitor of Quora again.🤦♂️
Did you ever see history portrayed as an old man with a wise brow and pulseless heart, weighing all things in the balance of reason?
Is not rather the genius of history like an eternal, imploring maiden, full of fire, with a burning heart and flaming soul, humanly warm and humanly beautiful?
--Zachris Topelius
|
|
|
|
|
A group of researchers from Tel Aviv University recently discovered how shockingly easy it is to identify a person based on a tiny sample of their musical listening preferences. Deep Down Trauma Hounds (Skinny Puppy); Escape Artist (Zoe Keating); Two Sisters (Clannad). Checks out.
|
|
|
|
|
The week-long tabletop exercise, now in its third day, aims to find out whether our current technologies, systems, and institutions could handle the crisis if an actual asteroid were to threaten Earth any time soon. Incoming!
|
|
|
|
|
Didn't 911 occur on the same day that a 911-style emergency management exercise was taking place?
And didn't the current pandemic begin just a month or so after an international modelling exercise of a very similar pandemic disease took place?
Just... you know... noticing. Synchronicity is really strange sometimes, isn't it.
And there do seem to have been a lot of reported fireballs/bolides recently, more than usual.
2021 is going to be a great year.
|
|
|
|
|
markrlondon wrote: And there do seem to have been a lot of reported fireballs/bolides recently, more than usual.
Where's Bruce Willis when we finally need him?
Freedom is the freedom to say that two plus two make four. If that is granted, all else follows.
-- 6079 Smith W.
|
|
|
|
|
Microsoft has announced that the Windows May 10th 2021 Update (21H1) is complete and being prepared for release. Incoming!
|
|
|
|
|
The Bytecode Alliance, formed by Fastly, Intel, Mozilla, and Red Hat to move WebAssembly beyond the browser, has created a non-profit organization with the help of Microsoft to further their cause. Shining a silver light on the technology
|
|
|
|
|
Producing effective code means understanding more than just programming As opposed to the rest of us?
Although what he is asking for is kind of hidden in the language of that headline. (dang English, and words that mean multiple things!)
|
|
|
|
|
|
If you have a multi-monitor setup for your Windows 10 PC, you would have experienced this annoying issue often. The most annoying part is that this has never happened to me
One monitor, one monitor. This guy is a technical bore.
|
|
|
|
|
I wonder if that's what's going on with my work laptop, although it'd require one of my USBC-HDMI dongles having a hidden DP-HDMI converter inside, since it always is the same effect: Everything on monitor A moved to Monitor B (the primary display), I'd just assumed the dongle running A (or possibly A itself) was too slow to restart coming out of sleep and Windows gave up and decided the monitor wasn't there a moment too soon.
EDIT: Engadgets writeup of this makes it clear that my problem is this and should be fixed whenever this change comes out.
Did you ever see history portrayed as an old man with a wise brow and pulseless heart, weighing all things in the balance of reason?
Is not rather the genius of history like an eternal, imploring maiden, full of fire, with a burning heart and flaming soul, humanly warm and humanly beautiful?
--Zachris Topelius
modified 29-Apr-21 10:34am.
|
|
|
|
|
We've never seen a Mars rover from this vantage point before. So they're both on the same sound stage?
|
|
|
|
|
Users couldn’t care less about the programming language you used or how beautiful, clean, modular and maintainable your code is. In fact, they don’t give a crap about it. That's a relief
|
|
|
|
|
Yes, but I do.
And ultimately the user does, though they don't know it. Ugly dirty monolithic unmaintainable code has a way of revealing itself to the user as bugs, performance problems, stupid UI's, absurd menus, and general "wow, this stuff is crap but we're stuck with it" grumbling and complaining.
Quote: Ultimately, there is no right or wrong approach
I despise it when people say that. Yes, there is a right approach, yes there is a wrong approach. If you think there isn't, all you're demonstrating is that you aren't thinking. It's like when someone say "everything is relative." It's always amusing to point out that they just made an absolute statement.
|
|
|
|