We used (enforced) a writing method for software developers of three categories: So Far, More To Go, Save It For Later. It was something like a personal Kanban board for project members sharing a real schedule in weekly compiled/tested feature deliveries. This was a visibility feature for schedule and release rationalization. There were no Hail Mary pass negotiations or requests permitted. The prose mattered and project leads were forced to read them. It was not anything that could be rushed at the end. "Save it for later" kept team time boxed and synchronized and gave managers features to schedule for future version releases and sales messaging. We fired people who could not write English right alongside their Java and PL/SQL. It worked great. 100% project completion over 125 projects. I attribute it to HR weeding out ADHD gamers suffering bad grammar of inadequate educations needing paychecks. Software is 100% a product of communicative action. There are few excuses for execution failure absent bonafide academic grand challenges.
"We used (enforced) a writing method"; "project leads were forced to read them"; "We fired people who could not write English right alongside" (emphasis mine in all cases).
Forgive my bluntness, but your place of work sounds awful.
"I attribute it to HR weeding out ADHD gamers suffering bad grammar of inadequate educations needing paychecks."
Ironic, considering how poorly constructed this sentence is.
You treat people like children and they will act like them. Let me reiterate: your place of work sounds terrible.
> "We fired people who could not write English right alongside"
The rest of the "features" of the GP workplace aside, this one is something I wish I've seen more often.
Would you read a novel riddled with language errors? Where no sentence connects seamlessly to the next? Where there's an order of magnitude more implicit content to track than what is actually written? Where all the usual rules of orthography and punctuation are casually ignored, for no apparent reason? Where there's no structure to follow and things happen in a pretty much random order?
I wouldn't. Yet I have to read hundreds upon hundreds of pages of code written in such a fashion. It's not just about aesthetics - code like that is harder to work with and, I think, in most cases is a net loss in productivity, ie. it would be better if that code was never written. I understand not all the code can be written with sufficiently well-worded comments and docs, but there should be a limit to how bad things can get!
In other words, if you don't want to be treated like a child, please start writing like a grown-up instead of like a 5 years old who's convinced he's the best writer in the world.
I think we may be in danger violently agreeing, and perhaps I should have added a bit more nuance to my previous comment:
- I've worked with plenty of people over the years whose first language is not English, so I don't necessarily expect the most wonderfully written prose in comments and documentation (or anywhere else).
- I'd much rather somebody used expressive variable, method, type, or function names than wrote a ton of comments. Nowadays, with reliable auto-complete, and masses of storage there's really no need for terse naming. That being said, the odd comment to convey intent can be great. Reams of comments tends to be a smell because, even with the best intentioned teams, when the pressure's on they tend to rust, which in itself can obviously become a problem. Some might argue that incorrect documentation can be worse than none at all.
- I do like people to write descriptive commit and PR comments: "fixed a bug" or similar is obviously not acceptable.
But a lot of the above is about professionalism and taking pride in what you do, rather than being something that needs "enforcing". In other words it's something you want to deal with by hiring and promoting the right people, who are going to provide an example for others to follow.
In my experience people who work in tech are not on average known for their love of being told what to do (although to be fair that applies many people) so it's more about creating a culture that leads to the outcomes you need than trying to enforce behaviours.
We indeed are in general agreement, but the devil is in the details - and there are many details to discuss.
Are you a native English speaker? I'm not, and I could easily claim that your first point is condescending to the point of discrimination. I know it's not what you're trying to say, but treating non-native English speakers like dimwits who can't even properly learn the de facto language of their profession may be actually offensive to quite a lot of people. It's entirely possible to learn a language well enough to be able to write clearly and correctly (mostly! mistakes happen) in terms of grammar, vocabulary, and punctuation and, personally, I believe it's a programmers' duty to do so, natives and non-natives alike.
> I'd much rather somebody used expressive variable, method, type, or function names than wrote a ton of comments.
But of course! However, the sad truth is that people who can't write good (meaning understandable and mostly correct) prose also cannot write readable code. Searching for a good name for a variable, method, type, etc. is the same process as searching for a good word to put in a sentence, to structure the sentence correctly or to make sentences flow naturally in a paragraph. If someone cannot write readable English, then how is he going to write readable code, which is actually even harder, because the rules of the language are much stricter? Some people use comments as an escape hatch which allows them not to think about the readability of their code and they should probably be fired, because both their code and comments suck. I believe the brilliant coder who can't write clearly in a natural language is a myth: it may not be "wonderful", but writing at least clear and succinct prose is doable for most competent programmers.
I think the difference of opinion between you and me here is that I see readability of source code as a single whole, encompassing things from naming temporary variables, to naming methods, classes and modules, to writing comments, docstrings, tests and examples, to writing docs, readmes and issue descriptions, while you seem to consider these things separately.
To summarize: programming is, from lowest level of programming language syntax to highest level of cooperating with teammates and clients, about communication, with a heavy emphasis on written communication. People who can't write prose are worse programmers than those who can. Whether you want or can work with such programmers is of course up to you.
You'd be surprised how many people have no idea about English and they are pursuing development career. Successfully even. There are companies where you can consider yourself lucky if half of your team speaks English.
English is one thing - knowing it enables access to a vast body of knowledge which is not translated to your native language, but you can - in principle - be a competent developer without ever learning English. It will be harder because you'll have a lot fewer books, articles, talks, blog posts and so on to read and listen to, but it's possible.
Writing is another thing. In my opinion, you cannot be a competent programmer if you are unable to communicate well in writing.
A private company is NOT A STATE. DC is a right to work state. We fire people for any reasons. I had a pro PWC recruiter as employee #11. We were exemplary in practice. But nobody "gets jobs." That is unskillful thinking. People "make things." I need not argue. Go read "The McKinsey Way." That is a famous company where smart people like to work. They run an attrition hierarchy. They have a famous hierarchy of priorities: Customers 1st, McKinsey 2nd, Employees 3rd. Language deficits are never customer problems. Is this a support group for Matrix Neo Masters of Swift rewrite future? Too bad. Heroes write paychecks. They make the rule their customers need. Machines rust. Flesh rots. How philosophical do we have to make this?
I don't want to beat a dead horse, but I was playing with words. A method is a protocol defining a group for a project duration together. We call numerical recipes methods but they are more like refined tools we apply selectively. Methods are more than a point solution preferences. I have yelled at the BSOD and typed harder at the machine. But software engineering is a pure communicative discipline. The "enforced" was rhetoric. All methods are mutually enforced like a grammar.
Of course it is. Culture is very important to one's job. In fact, if you don't like you're job, you're not going to do a good job. Some companies make millions off of that premise (see Bonusly).
I actually completely agree with the idea of prose being written alongside technical requirements, but the work environment (and your tone) sound god-awful.
Back then educators and technical writers knew about pervasive passive voice writing problems. Brad Cox (Objective-C) ran our library and formalized onboarding. These were dark ages. Blog writing was yet to be. We walked people through "Dynamics of Software Development" and handfuls of shorter articles during lengthy onboarding. We shared examples of good writing. Project kickoff automaton was still instruction based and tarball then. We ran an internal early "best practices" Wiki to let people write more. We worked in groups on special projects more than task fulfilment. Group composition was important to clients. Our developers often shared our office space with clients on daily or weekly bases. We did a good job of doing a good job possible for that era. [Edits: typos]
I think that's short-sighted because if smart, clever people don't enjoy working for you they can and will find work elsewhere. Net result: you have to spend a lot of money and time hiring yet more smart, clever people, and so on.
Can't argue for those results, but I wonder who decided "who could not write English"? Some other effect may be at work... e.g, perhaps having people who thought and communicated in compatible styles.
Wow! With such a hostile environment, I am surprised that you are able to hire any developers at all. I am also surprised that you have the luxury of firing employees. I would imagine that the unfortunate developers who joined your company to sprint and go as far as possible from company like yours.
Your English is okay, you used initial caps after a colon for a sentence that is a dependent clause. 'It was not anything' needs help. Team time, should probably be team-time. Proofing is reasonable, though you missed the 'grammar of' which I assume should read 'grammar or', then the education should not be pluralised. I don't disagree with your point though :)
I enjoy literate programming in part for some of the benefits this article describes. Even if the documentation is separate from the program, sometimes escaping into writing for a while provides a sufficient amount of relief to just get back into hacking. Since the matter is related to the task at hand, it also helps me to organize my thoughts and be better prepared (and therefore less stressed) to re-introduce myself to the problem.
I also use hand-written notes. This allows me to escape a screen entirely, write candidly about whatever I please, and naturally reform the stress into something workable.
I have also found that it helps to put swear-words in the commit messages when I'm struggeling a lot with something.
Once I get to that point I will stop working on that specific problem until the next day, but swearing about it in the commit message helps me not think about it anymore and also when I come back to it the next day I can see from the commit what I was struggeling with.
Obviously only do this for repositories that you aren't sharing with anyone.
You could also do it in a shared repo if you don't push the commits and you squash them first. Personally I'm not a squash kind of person and I'd also fear that I pushed without remembering to squash even if I really were planning on squashing.
This study gives credence to the GTD's book claim that putting all of your tasks in an "inbox" reduces stress, which was the only worthwhile insight I got from it.
What about the two-minute rule for processing said inbox? Or defining projects as TODO's that require more than one step to complete? The GTD book has been a gold mine for me.
Great link! I found it very possible to read; I read it at least 2.5 times across multiple physical and digital copies of two editions. Turning the words into actions is the hard part for me. Surely this is the format that's going to work :)
For me, turning the words into actions was the easy part. The hard part was sticking to the habit of doing weekly reviews. I always fail at this after few weeks, and if you don't do weekly reviews, suddenly the whole GTD methodology falls apart on you and you have to start over...
Same here. The only thing I apply from GTD is that if the task can be done under 5 minutes do it.
Making todo lists and sticking to them require too much discipline. In my professional life I keep todo lists, reminders etc. But in my personal life I'm a lazy lazy person.
I write daily to-do lists either in the morning or the night before, on a small post-it note sized stack of paper. Throw it away at the end of the day, whether or not I finished everything. I try and be realistic and still usually end up with 1 or 2 tasks not done.
It's nice crossing things off, it also never gets out of control.
Of all the things I tried in my personal life to get more things done, this is the one that's generally worked. I still go through phases of not doing it but it's really easy to start doing it again as the stack is always on my desk.
The other thing that works very effectively for me, much like this article says, is occasionally when feeling overwhelmed I write down everything that's stressing me out in a temporary text editor (an unsaved notepad++ note, which remains between computer restarts). I include things like "I'm pissed off with Bob because he did X" or "I'm worried about client Y not being able to pay their bill" or "I feel like I'm not putting enough time into doing Z".
I almost immediately stop stressing about it, and generally end up closing the unsaved note after a week or two, usually without reading it again. When I do, most of the stuff I was worrying about turned out fine.
I just recently read about this in the You Don't Know JS series of books:
"We can be tempted to look at var a = 2; as one statement, but the JavaScript Engine does not see it that way. It sees var a and a = 2 as two separate statements, the first one a compiler-phase task, and the second one an execution-phase task.
What this leads to is that all declarations in a scope, regardless of where they appear, are processed first before the code itself is executed. You can visualize this as declarations (variables and functions) being "moved" to the top of their respective scopes, which we call "hoisting".
Declarations themselves are hoisted, but assignments, even assignments of function expressions, are not hoisted.
Be careful about duplicate declarations, especially mixed between normal var declarations and function declarations -- peril awaits if you do!"
It is hoisted at runtime. There is no compile/transpile step that physically moves the declaration to the top, so syntactically the declaration can be after variable usage.
"If you can't explain what you're doing to a 6-year old, you don't know it yourself" (ascribed to several famous physicists).
This is pretty true, and thus the exercise of explaining things in plain prose is very useful to make you polish your understanding, and find any problems in it. When hand-waving is not acceptable, problems in understanding become very visible.
Even if nobody reads this, it's very useful if node honestly. Having other people to read it just keeps you from slacking off.
I think the point is to externalize the concerns. If you only think about them, they are still "on your mind", whereas if you write them down, they are in a conceptual external storage and you can stop thinking about them.
I absolutely agree with the article. I personally keep a daily journal and it helps me a great deal - relieve stress and everything. Kinda cool for productivity as well. You just vizualize things when you write and then have not so many problems actually doing them.
"The effect of expressive writing on the error-related negativity among individuals with chronic worry."
> The error-related negativity (ERN), an ERP elicited immediately after errors, is enlarged among individuals with anxiety. The relationship between anxiety and enlarged ERN has spurred interest in understanding potential therapeutic benefits of decreasing its amplitude within anxious individuals. The current study used a tailored intervention-expressive writing-in an attempt to reduce the ERN among a sample of individuals with chronic worry. Consistent with hypotheses, the ERN was reduced in the expressive writing group compared to an unrelated writing control group. Findings provide experimental support that the ERN can be reduced among anxious individuals with tailored interventions. Expressive writing may serve to "offload" worries from working memory, therefore relieving the distracting effects of worry on cognition as reflected in a decreased ERN.
The study is not shy about what conclusions should and shouldn't be drawn from it. There is large "Limitations and future directions" section. Here are some excerpts:
> Although the current study sheds light on the utility of expressive writing in reducing the ERN among worriers, there are limitations that should be addressed in future studies.
> First, the samples size (N540) was rather small for a between-subjects investigation, and, unfortunately, this is the rule rather than the exception in comparable cognitive neuroscience studies (Holmes & Pizzagalli, 2010; Klawohn et al., 2016; Olvet & Hajcak, 2012)
> Second, we examined the ERN only after participants engaged in the writing and were therefore unable to assess how these processes changed from before to after writing.
> Third, we did not include a low-worry control condition. The purpose of the present study, however, was to provide a very specific test of the effects of expressive writing on the ERN in individuals with chronic levels of worry. Indeed, we meant to build upon the prior study that tested the effect of attention bias modification on the ERN (Nelson et al., 2015) by examining high-anxious individuals instead of college students sampled without regard for anxiety symptoms.
> Fourth, because we utilized a student sample, it would be useful to examine the effects of expressive writing on the ERN in clinical samples in future studies. However, as we detailed in Method, the individuals in our sample reported worry symptoms that were comparable to previous studies of patients with GAD, and by using a well-validated measure in the PSWQ, it is likely that many of our participants had GAD. Moreover, college students are not immune to psychopathology.
