Tag Info

Hot answers tagged

27

There's much more to programming than 'writing code'. A big part of being a successful programmer involves communication; Being able to connect with customers, understand their needs, translate them into the technical realm, express them in code, and then explain the result back to the customers. Programmers who have a hard time expressing themselves ...


21

Writing is hard, good writing is even harder. The thing about trying to explain something is that it requires more knowledge then just "kinda know it". I find that by blogging I 1. find out related topics that I need to understand, 2. identify where my understanding is shallow Read through these slides http://www.ai.uga.edu/mc/WriteThinkLearn.pdf. They ...


19

I don't know of any formal studies of the effects of programming language usage on native language competency, but I can share anecdotal evidence and pet theories. First off, even speaking more than one natural language has interesting side effects. If, for instance, I were to travel to France, speak only French for several years, and return to the United ...


17

Points to keep in mind when doing technical writing: Know your audience Know what they expect from this document, know how much background you can be sure they have. If your audience may span a wide range of abilities, add a glossary and/or appendixes to help bring the least able up to speed. Know the subject. You must have a mastery of the topic beyond ...


15

LaTeX is what you need. MiKTeX - for Windows. Text Editors Kile - for Linux. TeXnicCenter for Windows. Documentation Free LaTeX documentation. Complexity comparison


13

If you can't explain something well enough you probably don't understand it well enough Being a smart person means you will work with other smart people and you will have to communicate with them effectively. Any great idea you have is useless if exists only in your head Being able to communicate your ideas effectively is a sign of great understanding. ...


13

Did you read part 2 of the article or his sample specification? They embody a couple important principles when writing a specification. Don't overdesign. The purpose of writing the spec is to force you to think about important things like what happens when there's an error, and how you expect the user to interact with the system. You don't have to go ...


12

Indentation rules (most coding standards impose) really contradict rules of good writing, the way people perceive information, and the grammar rules. Making things (that group naturally, but not syntactically) inside parenthesis also contradicts how texts are usually typed. If (you try to type text that way) you'll face misunderstanding even ...


12

Practice. Simply writing and reading what you've written will make you a better writer. Start a blog and get some practice by writing articles on technical topics you're passionate about. ** The added bonus is all the stuff you'll learn while researching your posts.


8

Executive Summary: Put the important facts at the top then expand below. Details: When I have a long technical email that I fear will lose half the audience, I make an effort to put a short, accurate "executive summary" at the top, and include the complete technical details below. Selective use of bold or underlining also helps.


8

Keep a programmers/developers journal and try to write something in it every day. A technical blog works as well. The important thing is to write about the technical decisions you make like: Why you designed a class in a particular way The implications of an architecture decision The development process for a particular algorithm or method of which you ...


7

Some tips from this unknown technical blogger: Verify (not just read) code that you've entered by cutting and pasting from the preview to the command line or a text file to run. Several things (like line endings, indentation, and Unicode characters) can get messed up when transferring from an editor (or shell) to a web page and back. Get a human to check ...


6

I guess it's just me, but I have the opposite problem. I usually have trouble thinking of all the details before I start writing the code and actually run into the relevant issues. Realistically, I usually have only a vague design in my head when I start coding something. My big challenge is getting myself to think of all the details and have a design ...


6

Isn't it the same as asking "does long term programming affect your ability to do Calculus" or "does long term Calculus affect writing in a native spoken language". We get good at things the more we practice those things. And conversely, if we stop doing something, over time our skills worsen at doing that task. You probably used to write a lot more papers ...


6

For my graduate thesis, I had a similar challenge and spent some time reflecting about what it was I was trying to accomplish. Putting a non-trivial amount of code in printed form brings up several challenges. Code is best examined and manipulated in electronic form, so how do you provide that maneuverability within the printed page? Quite a bit of the ...


5

If you want a better answer to your question and a real awakening as to how well you write instructional manuals, hand the lady at the desk your instructions and watch over her shoulder as she tries to follow. Don't interject; pretend your not there. Ask her to think outloud. Take lots of notes. Prepared to be shocked. Go back and rewrite the instructions ...


5

My advice is to look at tutorials that you consider good and copy their style. Some things that generally improve documentation: Be redundant. Repeating yourself with several examples goes against the grain of developers who like to never repeat themselves. But in documentation this is actually very important. It gives the reader more than one chance to ...


5

If the challenge for you is in designing and not implementing, maybe you need a different motivating factor: If it's a pet project (not for work), I actually look forward to seeing it come alive, so designing it isn't enough for me. When you come up with your own pet projects, what's the goal? Is it for something you need to use? If so, you can use that ...


5

If they're using a language that came out of the western world (pretty much all of them) they write left to right. Generally they'll use native language variables, comments and output, but the code itself is in English. It's also relatively common to hear people talking about programming in a non-English language peppering their conversations with English ...


5

We do peer review of all technical documents (functional specs, design docs, etc...) that almost always turn up something that I missed or should have done differently or could have explained better. After each review meeting I do a personal lessons learned exercise in my journal (whether I wrote the reviewed document or not). I then take the results of ...


4

I've been doing programming docs for about 25 years, from the Unix Programmer's Manual to Microsoft server apps. Technical documentation has a pyramid of priorities: Is it technically accurate? This is job #1. Once you introduce something that is not correct, you lose the reader. Is it complete? Have you documented all of the args, the return values? Did ...


4

You need rapid prototyping, at home. When you apply the same level of professional rigor on a private personal project, it easily results in over-engineering. It is perfectly acceptable to set a high standard for a personal project, but you must understand that you may not have enough resources (coding hours, in addition to your 8 hours of daily work) to ...


4

I think if we examine the question, we obtain the answer directly: Is an inability to express yourself in writing in a natural language such as English a hindrance of writing good code? What does it actually mean to write good code? Programs must be written for people to read, and only incidentally for machines to execute. - Abelson ...


4

I like LaTeX myself. It isn't fancy WYSIWYG stuff, but for me that is more or less an advantage as it lets you focus on the content instead of the design. It is also a lot easier to create consistent documents using LatTeX than by using some kind of traditional word processor.


4

You may want to know what is the practice for writing RFCs. This is RFC 2119: Key words for use in RFCs to Indicate Requirement Levels.



Only top voted, non community-wiki answers of a minimum length are eligible