|
API's are different. I contrast "user" documentation and "system" documentation. And I use Visio for both. And Excel. And Word. Creating "internets".
"Users" bother with none of the above. I create "user interfaces".
"Before entering on an understanding, I have meditated for a long time, and have foreseen what might happen. It is not genius which reveals to me suddenly, secretly, what I have to say or to do in a circumstance unexpected by other people; it is reflection, it is meditation." - Napoleon I
|
|
|
|
|
Gerry Schmitz wrote: My documentation mostly consists of (control) tooltips.
Ooh, I really hate apps that assume that I will have the same mental model as the developer, especially when I don't . The expectations can easily lead into traps one can't get out of, and worse, ditching the app or tool.
That said, it is really frustrating trying to explain something when you haven't established common ground from the start (the "your breakfast may be different from mine" problem). So at least having a purpose, concepts and usage approach documented will give users a clue as to where the code is going, especially if the app is 'special' (i.e. different to regular expectation).
|
|
|
|
|
I never release an app I wouldn't use myself. I understand the concept of "flow". At the end of any project, I know more about the users' problem domain, than the user. Preaching to the choir.
"Before entering on an understanding, I have meditated for a long time, and have foreseen what might happen. It is not genius which reveals to me suddenly, secretly, what I have to say or to do in a circumstance unexpected by other people; it is reflection, it is meditation." - Napoleon I
|
|
|
|
|
I view documentation as absolutely essential and just part of doing a good job. If class and function names are genuinely sufficient, then that's fine, but if you try and ask yourself all the questions that a new user of your code might ask, frequently there's plenty to document for clarity. I'm quite lucky in that I have a lousy memory, so when I return to my code later, I may not be that far from a new user of it myself! I find myself thankful to myself for getting the necessary details explained and documented clearly! I think if a user of your code has to read any of the code in your function bodies, your documentation is insufficient.
I also think it's also valuable if you can to spend some time writing code that consumes your code - essentially walking in somebody elses shoes. It can show you how easy or otherwise it is to work with, and can reveal opportunities to improve the design, or perhaps suggest function overloads you can provide simpler versions of to reduce any pain. If there's anything cumbersome or unintuitive about your code, you'll hopefully encounter it and be able to rectify it.
|
|
|
|
|
I started my embedded coding career in 1978. I was writing code for the Motorola 6800 by the op codes (we didn't have a 6800 assembler yet). Documentation was a definite requirement. I pretty much just automatically document my code since then. First, I know it's not necessarily me that's going to be taking care of the code, so I want it to be easy to understand my thought process.
|
|
|
|
|
Attack the parts list singer? (7)
"I have no idea what I did, but I'm taking full credit for it." - ThisOldTony
"Common sense is so rare these days, it should be classified as a super power" - Random T-shirt
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
|
just to get it outside Wales...
BOM parts list (bill of materials)
BARD singer / poet
attack - def.
Software rusts. Simon Stephenson, ca 1994. So does this signature. me, 2012
|
|
|
|
|
And you are up tomorrow!
"I have no idea what I did, but I'm taking full credit for it." - ThisOldTony
"Common sense is so rare these days, it should be classified as a super power" - Random T-shirt
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
|
I thought up a good one over the weekend, and I can actually remember it!
The timing tomorrow may be a bit off. I *should* be at my destination by then, but given it's 500 miles away and involves several modes of transport to get there....
Prompted by last week's comment from @megaadam, maybe we "regulars" should consider some kind of time constraint on ourselves.
For example, @OriginalGriff and @petepjksolutionscom should not be able to answer for one hour; I'd happily take a half hour hit, and maybe the immediately preceding setter should too. What say, peoples? Anyone got a better idea for spreading the joy?
Cheers,
Peter
Software rusts. Simon Stephenson, ca 1994. So does this signature. me, 2012
|
|
|
|
|
I'm fine with that.
"I have no idea what I did, but I'm taking full credit for it." - ThisOldTony
"Common sense is so rare these days, it should be classified as a super power" - Random T-shirt
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
|
We ( me and OG ) did do that for a while but it didn't make much difference
In a closed society where everybody's guilty, the only crime is getting caught. In a world of thieves, the only final sin is stupidity. - Hunter S Thompson - RIP
|
|
|
|
|
Given how rare it is for me (and maybe others) to solve the CCC, I don't think it would make a lot of difference.
|
|
|
|
|
agree.
>64
Some days the dragon wins. Suck it up.
|
|
|
|
|
Ok with me to
In a closed society where everybody's guilty, the only crime is getting caught. In a world of thieves, the only final sin is stupidity. - Hunter S Thompson - RIP
|
|
|
|
|
Just did a search for "javascript force to a number", since I was having trouble converting an enum to a number. The third result was to an article titled "The White House Task Force on Worker Organizing and Empowerment: Update on Implementation of Approved Actions". It didn't contain the work 'javascript.' God, Google is starting to really f***ing suck!
I did solve the issue (a syntax error in my calling code), but my eyes still hurt, and I expect they will for a while!!!
(but no smile - a huge frown!)
|
|
|
|
|
Maybe it was a sponsored link.
|
|
|
|
|
Maybe the word "force" made Google think it as some kind of military force.
|
|
|
|
|
I'm willing to bet the page contained the word javascript somewhere.
might have been "text/javascript" though.
|
|
|
|
|
Yep. As well as "You have JavaScript disabled. Please enable JavaScript to use this feature." in a class. Since I haven't disabled Javascript for the site, it didn't affect the view.
|
|
|
|
|
Weird I just tried and didn't get that
In a closed society where everybody's guilty, the only crime is getting caught. In a world of thieves, the only final sin is stupidity. - Hunter S Thompson - RIP
|
|
|
|
|
Perhaps you are signed into Google, and it is personalizing your search for you? I almost always do searches from an unsigned in browser. Before about 3 to 6 months ago, Verbatim search was _really_ good. Now it, and all other forms, seem to suck.
- edit: tried it in Bing and it was FAR better. I thought I'd never say that!
|
|
|
|
|
David O'Neil wrote: edit: tried it in Bing and it was FAR better. I thought I'd never say that!
Seriously, I've never found Bing to be all that terrible. I'd go as far as saying it's as good as Google's ever been, but at least they haven't yet followed Google's current trend to make everything suck.
|
|
|
|
|
I find for most technical/code searches, bing is far superior, often giving me the code snippet from the most relevant stackoverflow post in an easy to copy view. But I am a .net programmer, so most of my searches are C# on Windows based. Plus, they've continued their bribe program and I accumulate points I can eventually trade in for Amazon gift cards. I HAVE turned off the chat functionality, though. It's not as accurate as the standard search.
|
|
|
|
|
LeahAtWork wrote: I find for most technical/code searches
True, that's mostly what I search for generally (which is why ads annoy me to no end but that's another story).
Yet it used to be that searching for some API documentation yielded better results on Google than on Bing (or MS's own API page). I can't say what it's like these days on Google, it's been so long I've explicitly gone there to search for anything...
|
|
|
|
|
I find the opposite.
Google is better than Bing, well for some searches anyway.
Neither of them are really any good in general anymore these days though, that I do agree.
|
|
|
|