|
There is only one right way - let someone else go for it and then read about their horror stories. 
|
|
|
|
|
 The correct answer 
TTFN - Kent
|
|
|
|
|
i see dead javascript code...everywhere...
Caveat Emptor.
"Progress doesn't come from early risers – progress is made by lazy men looking for easier ways to do things." Lazarus Long
|
|
|
|
|
“The reality is that Google has fundamentally sucked most of the oxygen out of the opportunities for people who create content to actually earn a living through advertising,” said Smith, who is Microsoft’s president and chief legal officer. In this crazy, topsy-turvy world, it's nice to know that some things will never change
|
|
|
|
|
Driven by hunger, a fox tried to reach some grapes hanging high on the vine but was unable to, although he leaped with all his strength. As he went away, the fox remarked 'Oh, you aren't even ripe yet! I don't need any sour grapes.' People who speak disparagingly of things that they cannot attain would do well to apply this story to themselves
Caveat Emptor.
"Progress doesn't come from early risers – progress is made by lazy men looking for easier ways to do things." Lazarus Long
|
|
|
|
|
Facebook is also ramping up internal developer support for Rust after targeting infrastructure written in C++. Looks like we have ourselves a bandwagon. Everyone aboard!
|
|
|
|
|
Didn't they say the same about D a couple of years ago. I thought that Facebook was a commonly-quoted example of where D is (was) being used in the real world.
|
|
|
|
|
markrlondon wrote: Didn't they say the same about D a couple of years ago.
Yes, but for whatever reason it doesn't seem to have gotten much traction. Wiki mentions Facebook, eBay and Netflix as prominent users. But there's no mention of D in that article.
So Rust now has most of the biggest of Big Tech behind it - Google, Amazon, Microsoft, Facebook. Just Apple who are missing.
I've been learning Rust in the past few weeks. There was another thread last week I think. Apart from the systems programming space it looks like it may have a sweet spot in WebAssembly where you can script high-perf and memory-safe components (say ML) from JavaScript or TypeScript.
It has a tough learning curve though. In rewriting one of my own programs from C# to Rust I was stuck for several days at one point trying to get it to compile! I got there in the end but it's just the first version I could get working, probably nowhere near idiomatic or even in the form I tried to get it into. But you have to walk before you can run. I did some timings (on a small ML example based on a book):
Python - 22s
C# - 1s
Rust Debug - 12s
Rust Release - 0.36s
At first I was horrified by the Rust Debug time then read:
"A release build typically runs much faster than a debug build. 10-100x speedups over debug builds are common!"
I guess I ought to do a C++ version but I haven't done any for over a decade and I don't currently have it installed.
Kevin
|
|
|
|
|
I believe that there are two main reasons software engineers don’t write documentation. Tools play their part but they are a hugely distant third. Present company not included. (I hope)
|
|
|
|
|
Quote: Writing is a tough, demanding task. It requires organizing our thoughts clearly, examining them critically, and expressing them clearly.
Isn't that also true for programming?
So if you can't write documentation because of the above....finish my sentence. 
|
|
|
|
|
In one sense, the need for critical examination and clarity is absolutely true for programming, because either the code works or it doesn't. However, code that works isn't always expressed clearly.
Writing is different in that there isn't as an objective measure of whether it "works" or not. You'd have to survey its intended audience to assess how well it works. Writing is also a different skill. Granted, technical writing isn't creative writing, but we don't expect writers to be good programmers. So technical writing is often done by specialists, which has the advantage of bringing in the perspective of someone who is more removed from the software.
|
|
|
|
|
So, write your documentation - actually your plan - before coding, and
Quote: focus on documenting the choices and why they were made
Oh sanctissimi Wilhelmus, Theodorus, et Fredericus!
|
|
|
|
|
Writing docs isn't just hard but is very, very, very boring. It's also very time consuming. Writing good docs (which includes things like diagrams and examples) takes longer than coding.
And, from a personal advancement perspective, it doesn't win publicity or mindshare.
I can see no simple, fundamental way round these issues.
modified 30-Apr-21 5:43am.
|
|
|
|
|
markrlondon wrote: Writing docs isn't just hard but is very, very, very boring.
I don't see that as a valid point; imagine doctors not keeping dossiers up to date because "it is boring". It is paid work, and doesn't have to be particularly interesting at all times.
markrlondon wrote: Writing good docs (which includes things like diagrams and examples)
We'd first need an example of "good docs"; lots of documentation that I encountered looked "fluffy"; too many words, some marketing sprinkled in there, more diagrams and screenshots than needed - and sometimes severely lacking an index.
Always enjoyed MSDN. It's to the point, concise and makes relevant parts easy to find. Perfect balance between being understandable and minimal.
markrlondon wrote: And, from a personal advancement perspective, it doesn't win publicity or mindshare.
The articles here prove otherwise on the publicity front. After all, an article is a form of documentation, even if it should be written in a different style from the technical documentation for a project. And that exists, not for mindshare, but to make it easier to understand the project and its parts, which in turn reduces maintenance costs.
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.
|
|
|
|
|
markrlondon wrote: from a personal advancement perspective, it doesn't win publicity or mindshare.
That is a huge problem. It's just not recognized as "real" work by managers unless there's a customer willing to pay for it. 
TTFN - Kent
|
|
|
|
|
Kent Sharkey wrote: It's just not recognized as "real" work by managers unless there's a customer willing to pay for it.
Because they can't invoice it, but it should be part of the projects' cost anyway.
Good documentation saves a lot of money for large multiple-year projects; it's a waste if it is an internal tool that has a few lines of code. Managers call those "hidden costs", like rent.
Problem is not the documentation here. It is the quality of the manager.
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.
|
|
|
|
|
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
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
