I’ve been working on assembly instructions for the past few days. I had a few minutes so I decided to look up some examples online and came across this academic article on the subject. The equations are probably not so useful, but the commentary about the user experience confirms many of my assumptions.
IMHO, it’s rare to see programmers that understand the importance of documentation. It’s usually considered a necessary evil and therefore done rather poorly. Also, there is rarely time given to this function, due to the emphasis on efficiency in most engineering departments.
I’m editing a large word document for a client and it has many broken internal hyperlinks. I did some background research to find out if I should replace these broken links with cross-references but it seems like both types of links are fragile, so I guess it comes down to personal preference. I prefer cross-references because the linked text auto-updates. Although bookmarks are more flexible, in that they can point to anything, from my experience they are also more prone to deletion and/or corruption.