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 ...


22

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 ...


15

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


15

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 ...


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. ...


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 ...


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.


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 ...


7

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 ...


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 ...


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

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 ...


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 ...


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'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

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

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

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.


4

root - sub1 - sub1a - sub1b - sub2 - sub3 keep the indention consistent ( I used 2 spaces ) and use a <pre/> or <code/> block in your html you can try and make it look more like a tree control with a | if you want to stick to ASCII characters root |- sub1 |- sub1a |- sub1b |- sub2 |- sub3 our use Unicode ...


4

I find that programming has had an overall positive effect on my writing, even though while studying in the USA I took a 9 year break from writing in my native language. I have developed the patience to edit and re-edit my writings, (when I have the time to do so,) until they come out perfect. Just like I tend to refactor my code until it comes out perfect. ...


3

LaTex is most suitable for writing technical documents. It is a high-quality typesetting system; it includes features specifically designed for the production of technical and scientific documentation. You will find everything related setting up LaTeX and using it on the homepage. Also, you will easily find a lot of tutorials on using LaTeX online.


3

Present tense seems good to me. Precondition: Foo is in state X Operation: this and that happen Postcondition: Foo is in state Y all of those are in the present tense. Or if it is a "state of project" Version 10: has feature A, B, C and D Version 10.1: contains improvement to A. Fixes bug 1049 in B. Adds new feature E.


3

Who is doing the design? If you are outsourcing the design as well as the programming, then provide them with use cases. They will construct a design to minimally cover the use cases. If you are outsourcing the programming, then present them with a set of design documentation. There are many design templates out there, but if you need a head-start you ...


3

Unfortunately good writing skills appear to be rare among many technical people including programmers. The bonus is that with a little investment in improving your writing skills will make you stand out.



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