|
What's your document writing approach?
Since we’re in the middle of two projects; one successfully delivered and another in the air I am being asked to whip some docs for the garbage, if that’s where they mostly end up. I’ve been given, for the second time this time (the first time was with my previous employer) the task of writing a coding standards document for VB. Here’s what I scribbled in MS Word for a start. Then I went for the scolding I had to take, http://discuss.fogcreek.com/joelonsoftware/default.asp?cmd=show&ixPost=88097&ixReplies=2
And having come back from the tremor, I feel somewhat discouraged to continue this tone. I think they’d want something more formal and less breezy (I’ll steal a phrase, Joel, if you won’t mind). This is an excerpt, a start. What I usually do when I am asked to write a document is that I take most of the time off my seat that I can in between frequent checks on the Web for related material. Then I go back to the pen and paper and scribble short notes or notes to myself on the skeletal structure of the document. Sometimes when I cannot think of a skeletal structure, I start scribbling pieces of text wherever I can delimited by line breaks. What’s your document writing approach? Would you think it’d be a bad idea to present this sort of line to the angry bosses?
<MY DIATRIBE ON CODING STANDARDS FOR VB HEADS>
Hello, there! I am your new mentor, depending on who you are, in laying down rules you *can* follow when you write your next program using Visual Basic 6.0. However, I do not contend that your life will change on following these rules. Neither do I wish to make claims on increased productivity with my rules. These rules are more of a result of the six and a half years of my programming experience in Visual Basic mixed with attempts to plagiarize from relevant sources on the Internet. You can look at the references section to the bottom of this document to see whither from I’ve the really great (ahem)-original ideas stolen J. I used to write C++ programs and Windows API programs before I wrote my first Visual Basic program, so you’ll expect a slight bend towards the Object Orientation in this writing. If you already have your set of rules you follow while writing Visual Basic programs, please stick to them! I do not wish to impose my convenience on the world. It is not important what conventions you follow, but how religiously you follow them across your team of programmers. What you will notice as an advantage to following these rules, is that if you have not been following any rules whatsoever earlier, following my rules will improve the readability of your Visual Basic code across the whole of your team of VB programmers, help you divide work across team members following same standards and in some places, it will help you optimize your code for better performance; if you like going hell-for-leather on long drives in the middle of the night.
The last time I was asked to write a document on coding conventions for the convenience of Visual Basic programmers in my company, it was for a telecommunication software company called Sotas India Ltd. (www.sotas.com), now known as Mantas. At the time, I expected that I was on an exercise that would *change the way things would be done* and along the side make me more famous and rich J. Famous, it did make me. Everyone enjoyed reading them. No one followed them. So as a result, we still had a lot of sloppy code floating around on top of the marsh like that algae. Time, as they say, is the greatest preacher. So I had the time to become wiser and in my time, I learnt that there was no such thing as one standard of coding Visual Basic programs. I sifted through dozens of Internet pages hosted by all the who’s-who in the industry, right from Microsoft to Stanford university web sites, all having their own flavor of the convention. The moral of the story we are about to begin translated for three-year-olds is that if we like something and we want to adopt it, then we must make some effort to practice it in order to benefit from it.
Blah… Blah…Woof….Woof…
There are warped ideologies a dime a dozen about the most abused topic in the line of conventions for coding and that is, naming variables. Charles Simonyi or Charles Shobraj, whichever you choose, honestly I don’t care as far as your variables suggest their own purpose. Variable naming, I think, beyond the point that it is sensible enough not to include single character variable names, is something very personal; like sex or religious faith. I dare not ask you to take the 69th position if I prefer it that way. The experience must be yours. I have, for reasons of personal preference, developed a style. Since I am asked to convey a standard, I will divulge on what I prefer doing and you may or may not adopt this for your programming practice.
More Blah… Blah… Blah…
<TOWARDS THE END>
References/Further Reading:
· http://www.xoc.net/standards/rvbanc.asp
· http://support.microsoft.com/default.aspx?scid=http://support.microsoft.com:80/support/kb/articles/Q110/2/64.asp&NoWebContent=1
· http://support.microsoft.com/default.aspx?scid=http://support.microsoft.com:80/support/kb/articles/Q173/7/38.ASP&NoWebContent=1
· http://www.aivosto.com/vbtips/
· http://www.vbwm.com/art_1997/art_cntr.htm
· http://www.insteptech.com/techlibrary/vbbest_practices.htm
· http://www.xploiter.com/programming/vb/vb5_tutor/appa.htm
· http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnvsgen/html/cfr.asp
· http://www.freevbcode.com/ShowCode.Asp?ID=2281
· http://www.informit.com/isapi/product_id~%7BAC9FF62E-40B5-4D0E-AA83-C8AD9CA9F147%7D/content/index.asp
· http://www.digital-lenz.com/
· http://www.visibleprogress.com/downloads.htm
· http://www.visibleprogress.com/visual_basic_coding_standards.htm
· http://www.solutionset.co.uk/info/freeoffer.htm
· http://www.gui.com.au/html/coding_standards.htm
· http://www.freevbcode.com/ShowCode.Asp?ID=2547
· http://mindprod.com/unmain.html
· http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpgenref/html/cpconnamingguidelines.asp
· http://www.insteptech.com/techlibrary/oodesign.htm
· http://www.only4gurus.com/v2/download.asp?ID=4242
· http://www.xoc.net/standards/
· http://www.semdesigns.com/
· http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dncomg/html/msdn_basicpmd.asp
· http://www.aivosto.com/project/tutorial.html
· http://www.vbxtras.com/products/vblaw.asp
· http://builder.com.com/5100-6373-5032700.html
· http://abstractvb.com/code/code703.asp
· http://www.vb-faq.com/Articles/Fresle/VB_Coding_Standards.asp
· http://www.vbexplorer.com/VBExplorer/galaxy2.asp
</TOWARDS THE END>
</MY DIATRIBE ON CODING STANDARDS FOR VB HEADS>
Sathyaish Chakravarthy
Wednesday, November 19, 2003
How about - 'Keep it short?'
AJS
Wednesday, November 19, 2003
Give him a break! He is having 'one of those' days :)
Wednesday, November 19, 2003
>Give him a break! He is having 'one of those' days :)
Yeah! You're right. I also want to know how one of 'those' days is/was like for you. What is it like being asked to vomit out documents one after the other. And does it make sense to give this kind of a rhetoric to angered turtles or I must adopt a new line of writing that is more formal and less personal?
Sathyaish Chakravarthy
Wednesday, November 19, 2003
I can't even read one sentence because it's just a bunch of rambling. If you want to write a document specifiying coding standards then do so. If you want to write a thesis paper on coding standards then go to a uni. Most importantly it seems as if you're bored off your ass and you sure as hell aren't getting any work done by coming on this board and posting this garbage.
Wednesday, November 19, 2003
That was quite an honest opnion. Appreciated. I'd like more criticism. And I mean it. Thanks a tonne.
Sathyaish Chakravarthy
Wednesday, November 19, 2003
How about just having different sections, i.e., a section on commenting, another section on indenting, etc. with some bullet points under each section? This should make it easier to read and presumably more likely that the developer will actually read it.
Suggested sections: the aforementioned sections on commenting, indenting as well as sections on variable naming, error handling, object cleanup, usage of frameworks and class libraries (i.e., don't reinvent the wheel)
Michael Bolton
Wednesday, November 19, 2003
Great. I didn't write in the meat of the document in here because:
(1) I've for now only prepared the outline/headings/sub-headings for those topics you mentioned.
(2) It would get too lengthy and not make any sense having that long a post.
The idea behind posting this thread here is that I sincerely admire the way all you guys write. When I read all your posts, I am overwhelmed. I want you guys to tell me:
(1) What is it that you people follow as a document writing approach?
(2) What are the weaknesses in my writing style. One, someone already pointed out, it reads as though it was a bunch of ramblings. Great. I want some more honest criticism if you'll be kind.
If I can have a glimpse of something you senf off to your boss as an official document just to gage the tone.
BTW, I am also learning a lot of writing skills just reading the posts on this forum. Amazing. Thank you all of you guys. More comments please!
Sathyaish Chakravarthy
Wednesday, November 19, 2003
My approach is to write headings and subheadings, then do the key information in each section as bullet points, then expand the bullet points into sentences / paragraphs. What I was taught at school was: One thought = one paragraph.
Every so often I look at a section and if I've used the same form of words more than once, I try to vary the words used.
When I finished if the format doesn't require headings I remove them. and let the paragraph structure divide the document into sections.
Above all if there is a standard (cliched even) way of putting something I use that. Business letters beginning "Further to our conversation of ..." are as boring as hell - but they are clear and unambigous.
Hope it helps.
A cynic writes
Wednesday, November 19, 2003
Yes, it was helpful. You've given me a few leads here I can use. I usually end up writing all raw-material for my document on a rough paper first, which will include some ramblings, as someone just mentioned, along with topics/sub-headings I will like to talk about in the document.
What has been a learning for me in reading your words is:
>One thought = one paragraph.
and
>When I finished if the format doesn't require headings I remove them. and let the paragraph structure divide the document into sections.
Although I never used to do much editing to my writing sometime back, I've started that now. Especially before I post here because the kind of English you guys write is intimidating for a non-English speaker like me. I also edit my official docs that I am writing and these days I end up editing them again and again. Just like you said, I am also very conscious of the repetition of phrases I use.
Could some of you show me some of your official writing stuff in excerpts?
Sathyaish Chakravarthy
Wednesday, November 19, 2003
Don't bother reinventing the wheel. Buy all the developers their own copy of Code Complete.
Done.
Eric Budd
Wednesday, November 19, 2003
I'll try & sort some out tomorrow (it's going home time GMT) - it's also worth bearing in mind the version of English I write isn't precisely the same version of English I speak.
Hope all goes well.
A cynic writes
Wednesday, November 19, 2003
That will be iMMense help. A hearty thanks at that. I look forward to it.
Sathyaish Chakravarthy
Wednesday, November 19, 2003
>Don't bother reinventing the wheel. Buy all the developers their own copy of Code Complete.
If I could do that, I have a long list that I want to buy for myself.
Sathyaish Chakravarthy
Wednesday, November 19, 2003
>it's also worth bearing in mind the version of English I write isn't precisely the same version of English I speak
That applies to me too. You must hear me stammer searching for *that* right word while fumbling a dozen others as substitutes to convey the idea *as is*.
Sathyaish Chakravarthy
Wednesday, November 19, 2003
> Great. I didn't write in the meat of the document in here because:
<snip>
This post was great. It was concise and to the point. Why not adopt the style of this post?
www.MarkTAW.com
Wednesday, November 19, 2003
Wow! Clever guy, Mark!
Sathyaish Chakravarthy
Wednesday, November 19, 2003
I am begining to get better and better everyday (without help from Dr.J.B.Rhine, please!). I like being around here very much because of the great learning I get in your company. I love the way you guys just talk. You are all so darn good at everything that one only can better themselves everyday by reading this board. I like feeling inferior at times when I read you guys because that's a good thing to feel when you want to learn. Otherwise, before JOS I did not find contact with real life people who were super heros, except by reading articles but that's not first hand contact, right?
Sathyaish Chakravarthy
Wednesday, November 19, 2003
;-)
In writing there's the concept of "Show don't tell" and your writing was doing a lot of exposition. (Austin Powers anyone?) Like those Victorian Novels and scholarly works I can't stand reading that always tell you what they're going to tell you before they tell you. If the developers are being forced to read this in the first place, you want to ensure that it's as quick a read as you can make it, and well laid out so that they can refer back to it if need be.
Books on Speed Reading will tell you to glance at section headings first to get an overview of what's going on. Then scan paragraphs, then go back and read in depth what you want to read in depth. Odds are this is how your document will be read, not word-for-word, so keep this in mind when laying it out, and trim excess words to make the meat easy to find.
In other words, bold section titles, maybe in a different font, larger fonts for outer sections - your document should look like it was written in an outliner. Go to your favorite reference manual and mimic their layout style.
"In this book I will attempt to prove that Repitition is boring. By constantly Repeating myself I will prove to you that you can't stand Repitition. In the first part, I will rehash what I said just now. In the second section, I will present to you a sample of Reptition by rewording what I said in the first section. Third verse, same as the first."
I'm guessing you read Joel's essay on writing good requirements where he said to be humorous. I would submit that you should constrain the humor to places where you can insert it, like using humorous (to use Joel's example, names of Muppets) actors and variable names, rather than surrounding everything with it.
The tone and layout should be professional for the same reason you should wear a suit to an interview - you don't want to make a bad impression before you've even gotten started. This task was given to you, presumbably by your boss, and you should treat it that way.
www.MarkTAW.com
Wednesday, November 19, 2003
Whoops, inserted a paragraph so that my fictional victorian scholarly work seemed out of place.
www.MarkTAW.com
Wednesday, November 19, 2003
One lesson I've taken from the book, _On Writing Well_: be consise. English is littered with short mumble phrases which add bulk to a sentence without adding meaning. Eliminate them.
(Or I could have said: The English language is littered with lots of useless short mumble phrases which are used in order to add extra bulk to a sentence without adding any real meaning? Get rid of them whenever you see them -- see my point?).
It's hard to tell from a short example which is more readable, but imagine reading a 20-page document written in this style.
Use words sparingly. Write short sentences. Optimize your prose like you'd optimize code for a PIC microcontroller. It makes a difference.
Alyosha`
Wednesday, November 19, 2003
Mark, Alyosha, I am smiling loud, all of me is smiling inside and out.
Sathyaish Chakravarthy
Wednesday, November 19, 2003
At the same time, reading sentances without connecting phrases can be difficult to do. Paragraphs start reading like a laundry list of sentances rather than paragraphs.
Rather than focusing on the sentance level, I'd suggest you make each point once. Make it only once, and make it in the right spot in the document.
You may also want to read up on basic argumentation, and brush up on essay writing the way you learned to do it in college (or should have - forget the lessons of double spacing lines and padding your writing to fill out all 10 pages).
www.MarkTAW.com
Wednesday, November 19, 2003
>In writing there's the concept of "Show don't tell" and your writing was doing a lot of exposition.
Yes, thanks! I must work on that. But that is disappointing. When am I ever going to become one good writer? Then I'll tell you one more secret. When I know enough to write something inside a book, and when I have then mastered the art of writing, I will write a book just for the heck of it - because I want to. ;-)
>Like those Victorian Novels and scholarly works I can't stand reading that always tell you what they're going to tell you before they tell you.
Hey, that reminds me of Steven Roman's style of writing although I admire him fervently, especially for the chapter 6 titled "Strings" of his book "Win32 API Programming with Visual Basic".
>If the developers are being forced to read this in the first place, you want to ensure that it's as quick a read as you can make it, and well laid out so that they can refer back to it if need be.
Woo....I am crying now! I have a lottttt to learn.
>Books on Speed Reading will tell you to glance at section headings first to get an overview of what's going on.
Name a book on speed reading that is popular please? You are probably going to find me spellbound at every thing you mention. Hey, where do you get that? How do you do that?
>Go to your favorite reference manual and mimic their layout style.
Just one PJ I am tempted: Which is my favourite reference manual?
>"In this book I will attempt to prove that Repitition is boring. By constantly Repeating myself I will prove to you that you can't stand Repitition. In the first part, I will rehash what I said just now. In the second section, I will present to you a sample of Reptition by rewording what I said in the first section. Third verse, same as the first."
Interesting! Where do I get hold of this kinda stuff?
>I'm guessing you read Joel's essay on writing good requirements where he said to be humorous.
All the time! ALL the time. He's such a brat. Yesterday night I thought I'd take some hand outs on Coding Conventions from different Web sites so I could read them at home and come back this morning almost prepared. Somewhere in the middle of the 20th odd web-site I was visiting on the subject, I gave in to the temptation that was itching me to visit JOS again and re-read all those favourite articles from his archive. I went back and read a several of them again over for the umpteenth time. Then I took home some 200 odd pages of which more than a 100 were from JOS. And when I went home, I picked up one of his pages to re-read for the Nth time and then I wouldn't stop reading more and more, again and again. I was stationary, half-lying down, with the TV on in front of me, and my body paralyzed as if with some spell that had caste me into a statue, and my head leaned so my eyes fixed their gaze on the pages in my hands. It went on for hours until I fell asleep. The fellow did not even let me read what I had to be reading, he's so evil. ;0)
>I would submit that you should constrain the humor to places where you can insert it, like using humorous (to use Joel's example, names of Muppets) actors and variable names, rather than surrounding everything with it.
How could I not see that? I guess I did, but I needed someone to point out because I wasn't fully sure if I was kinda overdoing it and sounding like a jerk. Thanks a tonne. I must learn this art too.
>The tone and layout should be professional for the same reason you should wear a suit to an interview - you don't want to make a bad impression before you've even gotten started. This task was given to you, presumbably by your boss, and you should treat it that way.
When will I write something that's half as good as what Joel writes? Actually even a fraction will do.
Alyosha` writes
>Use words sparingly. Write short sentences. Optimize your prose like you'd optimize code for a PIC microcontroller. It makes a difference. '
I got your point. I catch myself doing that often. How do I correct it? I will work my way through. Do you think reading your own material over and again makes you see mistakes in it more clearly, if I must adopt that?
Sathyaish Chakravarthy
Wednesday, November 19, 2003
Proofread. And get someone else to proofread whose use of English you respect.
Michael Eisenberg
Wednesday, November 19, 2003
>Proofread. And get someone else to proofread whose use of English you respect.
That was the sort of thing I was trying to do with making this post actually. ;0)
Sathyaish Chakravarthy
Wednesday, November 19, 2003
Sathyaish Chakravarthy:
You talk too much.
timothy
Wednesday, November 19, 2003
The key to clean, uncluttered writing is not to write perfect prose the first time through, but to revise what you've written, relentlessly removing every unnecessary word and rephrasing every unwieldy sentence. A well tightened-up document often can be half the size of the first draft.
Alyosha`
Wednesday, November 19, 2003
Thanks, Alyosha`. You've been a great help. I will put into practice what you've said along with advise I got from others in this post.
And I will also try to talk less, :).
Sathyaish Chakravarthy
Wednesday, November 19, 2003
Joel's writing style is excellent, not only informative but somehow *fun to read*. I read up everything I could find in the archives, and wanted more.
But just following his writing advice -- "imagine actual persons" or "put in a joke or two" -- isn't enough. I think you own writing is a bit stuffy, too intense on "being cute" so people end up offended, and stop reading.
It's a tight rope, writing cute without being insultingly superior.
Alex
Wednesday, November 19, 2003
>I think you own writing is a bit stuffy, too intense on "being cute" so people end up offended, and stop reading.
That was very analytical of you. Did I not say why I love coming here again and again? I guess in time I will learn in your company and the company of others around here. But believe me, I have already begun.
Sathyaish Chakravarthy
Wednesday, November 19, 2003
I would rephrase the part you submitted as follows:
This document describes our company's standard for development in Visual Basic 6.0. Goals of this standard are to:
improve the readability of Visual Basic code;
help to divide work across team members;
help to optimize code for better performance.
At the bottom of this document you will find references that you can check for more background information.
Jack
Thursday, November 20, 2003
After a few hours of meandering around the web and then going back to it, I got it a bit straight-straight. I dig the idea is the just present the fact with a crispy face that cracks on exuding a smile. If you have to smile, just do it mildly. I've been re-working on it over 4 times now, editing it over and over again.
It now reads something like this: (these are excerpts from here and there, not in continuity)
<DOC>
Research has shown that the initial way in which software is constructed can have a dramatic impact on the lifetime cost of software and that enforcement of coding standards early in the development process can significantly reduce maintenance and future development costs.
Coding standards provide a consistent structure and style for source code making it easier for different developers to read and understand each other's code. When developers leave a project and new developers take over, the new developers will find it easier to understand the code if it has a consistent style and structure.
It is highly important that Visual Basic programmers in a team follow a professional discipline in coding in order to improve readability of code and make for easy maintenance of today’s code tomorrow.
Below is a basic protocol that is the hallmark of a seasoned programmer:
Coding Conventions
Optimization Techniques
Best Practices
Further Reading
Coding Conventions
This section concerns itself with defining a set of rules of programming grammar that you can use to make your programs more maintainable. I strongly recommend that you read the Microsoft Publication The Basics of Programming Model Design as an additional reading to this document.
IDE Settings
Without getting into much detail, you must learn to configure your IDE to suit the best practices. Open up your IDE and go to the Tools -> Options menu. From the Editor tab of the Options dialog box, check the Require Variable Declaration box, if not checked already. Move to the General tab, within the Form Grid Settings frame, check the Show Grid box and select the maximum resolution by filling the lowest possible values of 24 in each of the textboxes viz. Width and Height. From the Error Trapping frame in the same tab, select the option Break on All Errors.
Option Explicit
The Visual Basic compiler runs in two modes, the implicit declaration mode and the explicit declaration mode. In the implicit declaration mode you may not declare variables at all. To create a new variable, you’ll just use the new name of the variable and in its first assignment statement; Visual Basic will create it for you. This can be bad since it can lead you to making spelling mistakes in your program leading to creation of redundant variables with almost similar names but different spellings, causing havoc for the code maintenance people. The second mode i.e. the explicit declaration mode requires that you declare every variable before using it. In order to turn on the explicit declaration mode, you must write the Option Explicit statement as the first line of every module in your project.
</DOC>
There's lots more I've written but rather than flooding the thread, I just want to give a feeler so you could tell me if I'm moving in the right track. The sentences in first two paragraphs have been adopted and are from two different sources in the list of URLs I mentioned. Then I've ramified the Coding Conventions in this format:
Naming Conventions
Controls
Functions
Source Code Files
Constants
Arrays
UDTs
Classes and Objects
Menu Controls
Enumerations
Comments
Formatting, indentation of code
I am trying to keep it as laconic as can be this time.
Sathyaish Chakravarthy
Thursday, November 20, 2003
One more thing I did, like Joel does, I removed the list of URLs from the references section and now made hyperlinks inline wherever it was required in the commentary. This not only reduced the size of the doc but also led me to realize that the reader would gain better by being directed to the relevant link (one-at-a-time) while reading a portion of text, rather than be dazzled with the myriad of links thrown at him.
Sathyaish Chakravarthy
Thursday, November 20, 2003
You must be either a different Sathyaish Chakravarthy or a very quick learner! I like this a lot better, to the point, easy to read, keep us informed when you finish your book! (but keep it thin though ;-)
Jack
Thursday, November 20, 2003
I'm sure your bosses will like this much better. Though IMHO it still suffers from what I talked about in the "users blame themselves for bad design" thread. Twisted sentance structure.
In journalism there's a joke. "Backwards ran the sentances until reeled the mind." That describes the strange way they construct their sentances.
"Research has shown that the initial way in which software is constructed can have a dramatic impact on the lifetime cost of software and that enforcement of coding standards early in the development process can significantly reduce maintenance and future development costs."
How about:
"The initial way in which software is constructed can have a dramatic impact on the lifetime cost of the software. Enforcement of coding standards early in the development process can significantly reduce maintenance and future development costs."
Hmmm, still awkward, and I don't like the superaltives "dramatic" and "significant" they mean basically the same thing. Come to think of it, both sentances mean basically the same thing.
"Enforcing coding standards early in the development process can significantly reduce maintenance and future development costs."
I think that says it all. Sure cutting down 50% of your verbiage will make for a much less impressive looking document, but I think it's much easier to read.
www.MarkTAW.com
Thursday, November 20, 2003
Thanks, all of you and a special thanks to the person with the screen name "A cynic writes" for sending me one of your docs in email.
Sathyaish Chakravarthy
Friday, November 21, 2003
 Recent Topics
Fog Creek Home
| 
