|
the problem I usually find is that so called IT departments or contractors just don't listen when you explain what they need to do, think they know it all or plain just don't it. this then requires more too-ing and fro-ing getting them back on the phone to set the permission to that folder, sql database or login that you specifically told them they must do when installing, so the first you know it is that an irate customer cant do something so calls you first as its your product and you have to go through the whole process again - grrrrrr
|
|
|
|
|
The way it usually goes is you get a call that something isn't working, so you email them the installation docs, instructions or prerequisites (again!) and get them to check they have followed every step exactly. The reply comes back five minutes later "It's working now".
|
|
|
|
|
I had a good one today when a local IP address to a device 'disappeared' after the new IT contractors had been messing with the router - after mucho discussion we had to get the original guy back in sort it, which he did, and the new guy rang me later to tell me 'Ive sorted it now' - I couldn't let that one go so let him know in no uncertain terms that HE hadn't sorted it at all, it was him that caused the problem, wasted all our time & cost the customer money, and yet expected us to somehow be thankful HE'D solved the problem - my contact told me the new guy looked about 5 years old and seemed a tad upset, but my empathy with 'experts' vanished many years ago so I didn't feel in the least bit bad about it lol. GL
|
|
|
|
|
I was walking around campus today wondering where all the high end German made cars were hiding and then I remembered that the students are away on break.
|
|
|
|
|
Why is it that we as programmers hate to document?
I document code as I go but I write articles for my site on projects and libraries I create and I suck at it, put off doing it and when I do get down to writing it's a slow tedious process.
New version: WinHeist Version 2.1.0
There's a fine line between crazy and free spirited and it's usually a prescription.
I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
|
|
|
|
|
We are used to writing for a smarter user-base than the documentation's target audience.
|
|
|
|
|
The problem is I understand what I write but few others do.
New version: WinHeist Version 2.1.0
There's a fine line between crazy and free spirited and it's usually a prescription.
I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
|
|
|
|
|
Use examples.
Everyone understands and example
PooperPig - Coming Soon
|
|
|
|
|
I've noticed that Mike.
Life is like a s**t sandwich; the more bread you have, the less s**t you eat.
|
|
|
|
|
Tragic and true.
Mislim, dakle jeo sam.
|
|
|
|
|
I usually try to enforce a code freeze a few weeks before release. (depending on the size and complexity of the package). In that time I make sure to write the documentation and create install procedures and the like.
|
|
|
|
|
My code is self-documenting
I hate documenting my code (i.e. writing manuals), unless it is to teach others how to use a certain technology (like in my blog or articles).
And I'm not particulary bad at it.
But I do have a degree in Media and Journalism, so I may not be your average documentor
My blog[ ^]
public class SanderRossel : Lazy<Person>
{
public void DoWork()
{
throw new NotSupportedException();
}
}
|
|
|
|
|
Sander Rossel wrote: My code is self-documenting
As it should be.
New version: WinHeist Version 2.1.0
There's a fine line between crazy and free spirited and it's usually a prescription.
I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
|
|
|
|
|
The Documentors - weren't that nasties in Harry Potter?
Life is like a s**t sandwich; the more bread you have, the less s**t you eat.
|
|
|
|
|
Almost
My blog[ ^]
public class SanderRossel : Lazy<Person>
{
public void DoWork()
{
throw new NotSupportedException();
}
}
|
|
|
|
|
PhilLenoir wrote: The Documentors - weren't that nasties in Harry Potter? No, they had a different name and were just the end result of trying to document something.
|
|
|
|
|
Sander Rossel wrote: I hate documenting my code One company I worked for, we had documentors that created the documentation in parallel with us.
We'd occasionally upset the documentors when we found we had to change something, but we tried to keep it to a minimum.
That worked fairly well. Particularly since English was no longer the primary language for the programmers.
Psychosis at 10
Film at 11
Those who do not remember the past, are doomed to repeat it.
Those who do not remember the past, cannot build upon it.
|
|
|
|
|
Sounds a bit like pair programming, but with one doing documentation.
That might actually work...
My blog[ ^]
public class SanderRossel : Lazy<Person>
{
public void DoWork()
{
throw new NotSupportedException();
}
}
|
|
|
|
|
I really enjoyed it.
One case in particular, I had written what I called the "Custom Output Processor" for our database product. I had implemented an RPN style calculator so you could do math before displaying the results on the report. It also had commands for copying fields to the report. It was driven by a table of opcodes and arguments that were interpreted by the code. I had user opcodes like RCL, STO, PRT.
I was writing the next generation and wanted to make the processing orthogonal and was merrily adding new opcodes like INP, WRT, etc., and the documentor threw up her hands and declared it unteachable.
That caused me to pause and recognize she was correct. I redesigned it replacing all the different user opcodes with MOV and the arguments determined the internal opcode for processing.
I was particularly pleased because I made it code compatible with the earlier version. You may have written your processing in the earlier version with RCL and STO, but when you opened them in the newer version, you'd see them converted to MOV with the arguments indicating if you were reading a field, register, or an output field.
It really helped having a "non-technical" person commenting on what you were creating.
(BTW the database was The Data Factory published by Micro Lab, Inc for the Apple II)
Psychosis at 10
Film at 11
Those who do not remember the past, are doomed to repeat it.
Those who do not remember the past, cannot build upon it.
|
|
|
|
|
BrainiacV wrote: It really helped having a "non-technical" person commenting on what you were creating. Sounds useful.
BrainiacV wrote: The Data Factory Haven't heard of it.
BrainiacV wrote: Micro Lab, Inc Haven't heard of it...
BrainiacV wrote: Apple II Haven... Oh wait, I know Apple! The Apple II was released about ten years before I was even born (not to make you feel old or anything, I guess I'm just young)
My blog[ ^]
public class SanderRossel : Lazy<Person>
{
public void DoWork()
{
throw new NotSupportedException();
}
}
|
|
|
|
|
No offense taken. It was a long time ago, in a ... (wait, are you too young to recognize the reference? )
Beseech the God Google for "The Data Factory" "Micro Lab" and you'll find reviews.
It was an old flatfile database program.
And no, I'm not Bill Passauer, I was hired to clean up his, uh, code and myself and another ended up rewriting it completely. But that's another story.
Psychosis at 10
Film at 11
Those who do not remember the past, are doomed to repeat it.
Those who do not remember the past, cannot build upon it.
|
|
|
|
|
BrainiacV wrote: It was a long time ago, in a ... I believe that movie came out in the same year as the Apple II ('77) and it's one of my favourite movies ever
So I guess there goes my excuse
BrainiacV wrote: Beseech the God Google for "The Data Factory" "Micro Lab" and you'll find reviews. I won't actually
My blog[ ^]
public class SanderRossel : Lazy<Person>
{
public void DoWork()
{
throw new NotSupportedException();
}
}
|
|
|
|
|
Mike Hankey wrote: Why is it that we as programmers hate to document?
I must be some weird outlier because I actually quite enjoy documenting, everything from story boarding to code docs to architecture acceptance test procedures (probably nobody has heard of those things nowadays) to user manuals.
One thing that's fun about documentation is that I often have the experience "oh wow, I could have done that so much better this way."
I also find it interesting, in a sort of sad way, how little pre-code documentation is written, stuff like architecture, diagrams of component interactions, etc. To me, that stuff is like writing an outline to a book -- if you do it well, the book basically writes itself afterwards. Same with architecture / design docs -- do it well and the code "just happens." Sure, there are always sticky areas, but overall, that's been my experience.
Then again, we really don't have decent tools for a) documenting from code and b) coding from documentation. Even simple things like diagramming a state system or inter-module events, where are the tools to generate the code in a language agnostic way but still cognizant of the language features and framework the dev wants to work in? They don't exist. What I find tedious is not the documentation, but having a pretty diagram in Visio and then having to write the damn code, when I should have a tool to at least generate 90% of the code for me!
Anyways, enough of that soapbox.
Marc
|
|
|
|
|
I agree documentation tools are pretty much non existent, pity would really help poor souls like me.
I think my biggest problem is my grasp of the English language. One tends to fear what one does not understand.
You, Sasha, Nish and others have a writing style that I envy.
I excel in other areas; trivia, kick the can, distance spitting, etc..
New version: WinHeist Version 2.1.0
There's a fine line between crazy and free spirited and it's usually a prescription.
I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
|
|
|
|
|
Self Documenting Code... I always thought it was a buzz word way to get out of using comments/documentation, I have hardware projects to take over that were self documenting apart from the input, power amp it wasn't! same with code 'Oh I see what is being done, but why?' is a common in my experience!
|
|
|
|