Might be a bit dated now, but The Elements of Style by Strunk & White was one of the first books I read on writing.
Even if some of their examples or philosophies are dated, it's a really good foundational book. Having that base can save even the most boring or uninspired stories. Good writing can exist independently of a good idea (unfortunately).
If you want to learn to write well in English, this book taught me more than anything else.
Working in a regulated environment for over 20 years, I've seen and written a lot of architecture and design documentation.
You aren't going to be able to extract and architecture from the code automagicaly. Its going to require reading and understanding the code at a high level.
To document the architecture you break the system into a series of "views". A view is one way of looking at the system.
Example views are:
Module - List all the modules in the system and their purpose.
Layer - List the software layers, what they do, and how they interface.
Threads - List all the threads in the system and their purpose.
You can sprinkle in some class diagrams and sequence diagrams as needed.
These are some example views but are the main ones.
A good book on this topic is: Documenting Software Architectures: Views and Beyond
A mental model that I use when writing/explaining DS work is the inverted pyramid: you start with a general statement about the world, and move to ever more narrow/precise statements.
Eg, if you were writing about recommender systems, you might start with: "Figuring out what people want to watch is hard. Often, they don't know themselves." You'd end with "That's why I'm proposing [whiz-bang method that improves [metric] x%]." You'll have three parts of what you're saying: the "common ground," the "destabilizing condition" and the "gist of a solution." Basically, you're explaining why [thing] should change, and you want to keep it simple.
Non-technical users don't care about your modeling approach/hyperparameter selection/etc, to them, one magic black box is the same as another. In fact, that's probably the best way to communicate -- replace every mention of your model or algo with "magic black box" and make the rest of your case. If you can't do that, your argument is too technical, and you'll lose the audience; you need to make sure the case your making is relatable to them.
You should put yourself in their shoes, and ask "why do they care about this?" for every point you make. If you can't give a succinct answer to that, rework your argument.
A really good book for getting better at writing/structuring argumentation is The Craft of Research (3rd ed) (https://www.amazon.com/Research-Chicago-Writing-Editing-Publishing/dp/0226065669). They bought it for us in grad school, and I still have my copy, it was invaluable during my dissertation.
And as with most things, you'll get better if you practice :)
I thoroughly implore everyone to read <em>The Elements of Style</em> by Strunk and White. When writing, it's your best friend. If it were up to me it'd be handed out to every single NCO during BLC.
Here is an excerpt on the word irregardless:
>Irregardless. Should be regardless. The error results from failure to see the negative in -less and from a desire to get it in as a prefix, suggested by such words as irregular, irresponsible, and, perhaps especially, irrespective.
There's this cool book by K.E. Kuth (famous computer scientist) called Surreal Numbers. It's from 74 and a bit hard to get some times, but it looks like it's in stock in Amazon now and it's pretty cheap.
It's not really an instructional book, it's a conversation between a young couple, kinda like a play. They find a rock with a couple of rules and they essentially create a whole new number system from scratch guiding you through the whole process. No prerequisites required.
It's a short (apparently written in a week) and pleasant read. I think that it's also a great insight into how actual math research is and it's very different from classic school arithmetic and algebra, refreshingly so.
I do somewhat agree with you to a point. Understand that being able to write is a necessary skill for communication though. While commenting on someone's grammar in this setting is rather pointless as most people can figure it out, if you or someone you know has issues with writing there is a great book for it and it's only $5 from amazon. Probably less at your used book store.
I would recommend Strunk and White's The Elements of Style.
It's pretty much the definitive work on writing clearly and precisely.
I could do a lot of research for you and put it here, but I think it would be more beneficial for you to read a book called The Elements of Style, written by William Strunk Jr. and E.B. White. It's considered a great, if not the best, writing book out there, focusing a lot on style. I found a condensed version of the book as a PDF online for you. You can print it out and mark it up, or you can go online and buy the book there for a more comprehensive version. I'll put the link to the PDF and the Amazon purchase link for the 4th Edition if you want to do that too.
After you read that, don't stick to just that--you can branch out to other books. I haven't read much of Bird by Bird or Stephen King's On Writing, but I know there's some value in those books, or as I've heard from other writers. I've got other recommendations too if you'd like them.
Anyway, here's those links for you. Hopefully, I've been helpful.
There's three things I can recommend to help you improve your writing:
1) Get yourself a copy of Strunk & White's The Elements of Style. It's old, it's boring, but it's also been the gold standard of writing aids for decades, and for good reason. It's also like five bucks, so why not?
2) Read things. If you can, read worthwhile things. Get yourself a subscription to The Wall Street Journal or something. They offer student deals in a lot of places, and their articles are normally pretty top tier. But honestly even if you can't grind through that (I couldn't at 16) just read good writing. Fiction, nonfiction, who cares? If you read enough good writing, you'll start to pick up some of the strategies good writers use by pure osmosis.
3) This one is very important. WRITE things. Then edit them. Then edit them again. Annnnd another time for good measure. Then have someone you trust (maybe your English teacher?) edit them. Writing is like any other skill. The more you do it, the better you get.
And yeah, feel free to PM me if you have more questions, but honestly the best advice I can give you besides what I already wrote in the first post is: enjoy your life. Planning for the future is great and you definitely should think about it, but don't forget to stop and have fun sometimes. School (including undergrad) is honestly half about academics and half about learning how to interact with people. Later on they'll call that networking.
Strategic Writing for UX is a popular one. I started out by reading it and would recommend it.
I really like The Craft of Research, 3rd Edition. It walks you through all the various elements of writing research. Reports for stakeholders are a little different, but a lot of the ideas transfer!
Strunk & White. Very short, very clear, the only grammar/composition book you'll ever need. Can't recommend it enough.
https://www.amazon.com/Elements-Style-Fourth-William-Strunk/dp/020530902X
Chicago Manual of Style or Strunk & White, please
https://www.amazon.com/Elements-Style-Fourth-William-Strunk/dp/020530902X
The Elements of Style by Strunk & White is often recommended as the de facto grammar book, but I've never read it (though I think I own a copy somewhere) so I don't know how good those recommendations are.
I would recommend the Associated Press Stylebook as, in my experience, that seems to be the most commonly required knowledge clients expect you to know. There are often free guides available on college and university websites and elsewhere, though I'm not sure if those are published with permission or infringing any copyrights.
Other than that, I think the best resources to learn how to write well are really dependent on how you learn.
I personally excel at learning via immersion, so reading a lot and practicing writing usually has the most significant impact on the quality of my writing. (There's a marked difference in how well I write when I'm reading a lot vs. how well I write when I haven't read much in awhile.)
I think that writers who are unfamiliar with English conventions or who didn't grow up with English as their primary language could do well from immersing themselves in the type of writing they hope to emulate, i.e. if you're writing for American consumers, read the same type of content they'd be reading to try and discern what's common among each piece you read, how to craft contextual and relevant analogies and metaphors, how to alternate cadence, when proper grammar conventions are necessary and when you can get away with breaking those rules, etc.
I also think that this might be one of the rare occasions where it's worth looking into a course or tutoring to bring you more up to speed with the knowledge you lack. Maybe getting your hands on some middle or high school English textbooks could be beneficial too, especially since most online content aims to be written at a 7th-9th-grade level.
You essentially need two skills (at least) to start consulting.
1) Identify and solve the clients real problem (and not just the symptom) 2) Precise communication of the solution (or suggested approach to solve the problem)
I saw a post here earlier when someone recommended the book: Bulletproof Problem Solving. You need to learn a structured approach to problem solving. This book contains a great framework of 7 steps.
https://bulletproofproblemsolving.com
As of the communication part: All consultants would recommend The Pyramid Principled by Barbra Mintu
https://www.amazon.com/Pyramid-Principle-Logic-Writing-Thinking/dp/0273710516
The Craft of Research (3rd edition). It's all about how to come up with a question, frame an argument, and present what you did.
Your take is almost perfect! One small change: "This is a sentence (with some more stuff), and it ends right here (with more punctuation)." Periods and commas go outside of the parentheses for phrases, but the 'terminal punctuation mark' (i.e., final punctuation mark in a sentence) is used within parentheses for complete sentences. Example: "This is a sentence. (There's some more stuff, too.)"
​
If you haven't yet, I highly recommend checking out Strunk & White's writer's guide on English grammar and usage. It's one of the most well-known writing guides in the language and has been a huge help to me throughout my academic and professional careers: https://www.amazon.com/Elements-Style-Fourth-William-Strunk/dp/020530902X
Also, props to making it as a content writer in a non-native language. That's very impressive.
I assumed it is a cat.
No need for "that" as it serves no purpose.
There is a handy little genius of a book called Elements of Style by Strunk and White. 99 cents on Kindle.
Keep it simple. Less is more. Think of your reader. Your writing should be a transparent window through which your reader sees your content. Wordiness fogs up that window.
Maybe have a read of this!
It always hurt. Yet your supervisor made it even more painful. But I know cases when supervisors that mean that they say to students that they need to quit their studies because they are unfit for acadmia. So this is not a worst case scenario. I suggest you go meet your supervisor at office hours and ask them to explain to you why your proposal is not good.
Have you read this book by the way https://www.amazon.com/Research-Chicago-Writing-Editing-Publishing/dp/0226065669 It may help to gain more cofidence for supervisor talk.
You'll be fine, just move forward !
>OneMeterWonder · just now
>
>Would you please read back to me the first seven words of the article you’ve linked?
I'm not going to do your homework for you young person. I'm classically trained - in the pre-computer era. Boolean logic in the context of debate and classical structure is not as wiki-era accessible as you might prefer.
I asked you to do "the math" - that is why I am here. Are you here to merely dispute a common word?
A synonym for what I am referring to is "Logical Pyramid" - but it all stems from language as the basis for all thought, including mathmatics.
The conceptual foundation of Boolean logic as applied in academics of thought have been grossly polluted by their natural application to computer science, particularly data retrieval vis a vis search engines.
Naturally, this growth has cast a shadow over the functional use of Boole's process by semanticists, logicians and philosophers.
Let us agree that I am using the word Boolean (ie: from George Boole) as an outlier, and set that aside. Yes?
This might be something you would wish to review:
https://www.amazon.com/Pyramid-Principle-Logic-Writing-Thinking/dp/0273710516
I'd recommend a read through "on numbers and games" https://en.m.wikipedia.org/wiki/On_Numbers_and_Games As well as through surreal numbers https://www.amazon.com/Surreal-Numbers-Donald-Knuth/dp/0201038129
According to the textbook Technical Communication by Cunningham et al., your use of "which" in your second paragraph is suboptimal.
Here is the sentence to which I am referring for this grammatical correction:
> Overall, I enjoyed it, but it became tedious toward the end. Dickens tends to over-explain rather than leaving things up to the imagination, which makes the plot rather predictable.
Cunningham et al. specify that which is a relative pronoun that an antecedent, an object that "should be used to refer to a clearly identifiable noun or noun phrase, not an entire clause" (420).
The problem with your use of which is that it does not modify its antecedent properly. Think about it like this: does the "imagination" that you mention innately "make... the plot rather predictable"? It seems more likely that your "which" refers to Dickens's habit of over-explaining, yet "which" optimally refers to a noun or noun phrase, not a clause.
One of my kids wants to be a teacher. When I read posts like these, I always think, maybe one day they'll look for another path. I think this book gives good advice for beginners: https://www.amazon.com/Insiders-Guide-Technical-Writing/dp/1937434036/ref=asc_df_1937434036/
What you need to do is put together about 20 pages of technical documentation as a writing sample. Maybe watch a technical course on some complex subject (preferably related to software/programming) and then create a tutorial from your notes or something. Then leverage that sample as you apply for jobs.
Or you could actually attempt to write real documentation, such as by documenting something complicated at your work or perhaps documenting some technology you know (that is complex).
It's good that lots of companies are hiring now. Try to connect with others in local Write the Docs and STC groups. Look for a mentor.
My opinion?
This is editing. If this post is any evidence, you're a middling writer at best, criticism I only offer since you went out of your way to bash others here. You'd do well to read this book, particularly rule 16. It is the most important.
Read a lot. If English is your first language it helps to have that feel on what is correct and not.
Otherwise, The Elements of Style is a good book to have.
Get "The Elements of Style" - https://www.amazon.com/Elements-Style-Fourth-William-Strunk/dp/020530902X
... and study Dale Carnegie... if you're serious.
Read "The Elements of Style, Fourth Edition: Strunk Jr., William, White, E. B., Test Editor, Angell, Roger: 7447521286972: Amazon.com: Books" https://www.amazon.com/Elements-Style-Fourth-William-Strunk/dp/020530902X.
It's a very short and clear explanation of basic sentence structure and grammar, including comma use. While there are no official rules in English, it's a safe bet that every English Professor ever has read that book and will accept any common usage from that text as accurate.