16 ms·
Technical Writing Courses
- daxfohl 7y agoI'd love a technical PowerPoint course. I find writing to be pretty straightforward. But when manager is like "can you create a couple slides about...." total deer in the headlights.
- ct520 7y agoI know right.. Any similar resources for this?
- jedberg 7y agoSee my sibling reply.
- jedberg 7y agoThis book completely changed how I give presentations. https://www.amazon.com/Presentation-Patterns-Techniques-Crafting-Presentations/dp/0321820800/ref=nodl_ https://www.amazon.com/Presentation-Patterns-Techniques-Craf... You can find it on the internet at various price points. I even had a chance to give a technical presentation in front of the author and he said it was excellent, so apparently I internalized it’s lessons.
- riedel 7y agoI am a bit torn apart reading into it and watching a presentation by him. I think it might work well in some cultures and with some speakers. Being at a university seeing a lot of technical presentation by students I think he is quite heavy on presentations, which I typically always suggest to use really carefully my students and inexperienced speakers.
- emmelaich 7y agojust "torn" not "torn apart" -- which is quite a violent thing! "torn" in this context means to be not decided between a couple of opinions or decisions.
- deleted 7y ago[deleted]
- benjanik 7y agoDo you find the problem to be more around design or story telling?
- daxfohl 7y agoBoth, really. Maybe one driven by the other. I think of what I want to say, try to find a template, no template quite matches, pick one reasonably close, get bogged down by colors of arrows and things not snapping right, wonder if what I'm trying to say is no good or else there would be a good template already, start over in Visio, same process back to powerpoint.
- oggy 7y agoI've attended several short courses on giving presentations. This one by an ETH Zurich professor is the best one I know of: https://inf.ethz.ch/personal/markusp/teaching/guides/guide-presentations.pdf https://inf.ethz.ch/personal/markusp/teaching/guides/guide-p... He has a list of useful books at the end (I haven't read any of them, though)
- ghaff 7y agoPresentation Patterns, which a couple of people have mentioned, is probably more practical than most in terms of giving bite-sized advice though a lot of it is overkill (and not really even appropriate) for giving a manager a couple of slides about something. The thing with most of the presentation books out there like Presentation Zen is that they're really oriented towards a good presenter up on a keynote stage at an event using slides as a supporting element of a well-rehearsed presentation. That's not your typical presentation--and certainly not your typical internal monthly status meeting or project update. Presentation Patterns also seems to do a better job than most at acknowledging the realities of material that's both presented and needs a leave behind. The "standard" advice is that you should have two separate documents but that's really not practical in a lot of circumstances.
- enriquto 7y ago> But when manager is like "can you create a couple slides about...." total deer in the headlights. I'm just like that. But I received wisdom from a friend that helped me a lot. The following "three" rules: RULE 1. No bullet lists RULE 2. No bullet lists RULE 3. At least one meaningful image per slide, covering more than 50% of its surface Then, you explain your subject like you would to a friend in a bar, keeping the slides as useful side material.
- nogabebop23 7y agoMyabe your anxiety is because you're focusing on the "make some slides" vs. "deliver content in a presentation format". If you adhere to guidance for the later the slides are actually pretty easy. You quickly release they are just a prop that supplements the entire production. I found the video "How To Speak by Patrick Winston" delivered to new MIT students to be very helpful: https://www.youtube.com/watch?v=Unzc731iCUY https://www.youtube.com/watch?v=Unzc731iCUY Careful - once you become attuned to pp failures you will have little tolerance for them from both other people and yourself, and good presentations are a lot of work!
- aliabd 7y agoI've been working on this tool for a while that makes documentation easier and faster. The main idea is to have the code itself be the driver. Would love some feedback: https://trymaniac.com https://trymaniac.com
- cmurf 7y agoThe staggered screenshots that are ostensibly examples are all blank? Update: I see it works in Chrome but not in Firefox. Not sure why.
- deleted 7y ago[deleted]
- aliabd 7y agoNot sure either but will fix, thanks!
- j88439h84 7y agoWhoa.
- j88439h84 7y agoI want diagrams of my modules and how things are connected, such as one that shows "types defined in foo.py are used in bar.py". While you're generating docs from code, might think about diagrams.
- aliabd 7y agoThat's actually really dope, thanks! I bet we could do something there...
- deleted 7y ago[deleted]
- pncnmnp 7y agoHave you tried Pyreverse[1]? I used it for my Software Engineering course. From the documentation - Pyreverse analyses Python code and extracts UML class diagrams and package dependencies. [1] https://www.logilab.org/blogentry/6883 https://www.logilab.org/blogentry/6883
- boojing 7y agoThe content seems good but I'm not a fan of the way the sections are laid out on the introduction page. The courses should at the very least have hyperlinks for each of the learning objectives.
- yihsiu 7y agoI actually prefer the way it is. When there are too many links around, I tend to do some DFS-like reading and it ends up anxiety and tons of tabs. Things get worst when there're loops.
- 205guy 7y agoI found that turning my tablet sideways revealed a sidebar with links to each section of the courses. Sometimes responsive UI is not better.
- mattlutze 7y agoThere's a lesson overview on the left-side navigation, and an inner-lesson table of contents on the right-side navigation, which links to each topic or learning objective. If you're on a narrow format it looks like that table of contents is set into the top of the article below the lesson title.
- noisy_boy 7y agoI find writing documentation very relaxing. After a particularly busy dev cycle, it almost feels like a nice break. Maybe I should take one of these courses; I think we have more ageism in development than in technical writing (just a hunch without any evidence/citation).
- Aeolun 7y agoI want something like this but for Business Architects on how to write their requirements (and conversely, how not write the requirements)
- Too 7y agoGood resource. One common flaw i see in many technical writings, which i missed from the course, is treating the reader as a complete puppet. As in giving copy-paste instructions on what to do, but not explaining what's happening underneath. Better to teach a man how to fish than giving away a fish, or better condensed by Fred Brooks famous quote from Mythical Man Month: Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won’t usually need your flowcharts; they’ll be obvious.
- ghaff 7y agoTo be honest, that's a problem with a lot of in-person workshops and the like as well. There's a lot of type this, type that, run this script, etc. without enough context as to why you're doing these various steps.
- ntsplnkv2 7y agoYep - so many workshops could simply be a list of steps to do X. But often times the real world isn't that simple, and then the workshops are essentially worthless. With an understanding of how something works, I can apply it to more scenarios, or modify it to fit more scenarios. This is often woefully lacking in modern training/documentation.
- 205guy 7y agoThis is why “nobody reads documentation.” These courses are typical tech-writer overkill, missing the forest for the trees, then getting lost in the weeds (if I may mix a few metaphors). There is too much introduction and setup, then it jumps into the nitty-gritty, but never gives the big picture. Assuming this was written by the Google tech writers, I’m surprised at how middle-of-the-road the offering is. I kinda assumed they had an academic-like cutting-edge writing department. To write documentation, you need 2 things: an understanding of the subject matter, and a high-level understanding of what the readers want to do. The reader doesn’t want to use your API to list resources, the reader wants to give his/her users a list of resources for further operations. So you don’t give a trivial example of getting the list of providers, you give an example of how to display providers by getting the list and processing the various useful fields. It also helps if the API or UI or whatever is logical and consistent to begin with.
- federicoponzi 7y agoReally interesting comment thanks! Do you have any more tips for improving in technical writing? Do you know of any other good book / course on this matter?
- oggy 7y agoGreat comment about missing the forest from the trees. The course outline reminds me of an article on "writing great code" that lists the rules of a code formatter. My personal tips for writing docs: 1. think about what you need to get across and to whom. I've found this categorization helpful (just don't get religious about it): https://www.writethedocs.org/videos/eu/2017/the-four-kinds-of-documentation-and-why-you-need-to-understand-what-they-are-daniele-procida/ https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o... 2. try to say whatever you're saying with as few words as possible. "Vigorous writing is concise" is probably the best takeaway I got from Strunk & White (not a huge fan of the book otherwise) 3. do a few passes. "Keep rewriting" is probably the best takeaway I got from "On Writing Well" (but I like that book in general).
- 205guy 7y agoThe trick to writing that works for me is to combine tips 2 and 3 iteratively. I don’t write concisely at first (and I think that’s the case for most people), so I just write down everything I can think of related to the topic, even all the edge cases. Then I go back and simplify, maybe focus on a relevant example. I cut out fluff and stick to that example, perhaps with the list of edge cases in a separate section (and call it “Advanced Use Cases”).
- ChrisMarshallNY 7y agoI’ve been writing my entire life. I’ve found writing in the vernacular is usually the most effective approach (speaking only for myself -YMMV). In my opinion, I think that there are a number of “base class” rules for tech writing, but each subject domain really requires a distinct approach, as well as a clear understanding of the audience (and subject matter -but in my experience, being a good writer/teacher is more important than being a subject matter expert. The worst teachers I ever had were subject matter masters). But this is a cool resource. The one critical thing I find for my writing, is that the information I give be 100% correct, and the accompanying materials be absolutely polished and tested out the wazoo. If I’m speculating or unsure, I’m careful to note that. Mild humor helps, but I need to be extremely careful, and it’s usually self-deprecating.
- mattlutze 7y agoAfter reading some of the comments here, I'm wondering if people are actually following the link and reviewing the content. The two courses are well-structured. Each course has an overall outline listing each lesson, and each lesson has a table of contents to overview the topics therein. The courses highlight major key topics in technical writing and does so with easy-to-internalize (tenets). I'd have loved for my university coursework to be so clearly organized. Some highlights include defining your audience[1], engaging your audience[2] and reviewing how short and clear sentences improve comprehension[3]. 1: https://developers.google.com/tech-writing/one/audience#define_your_audience https://developers.google.com/tech-writing/one/audience#defi... 2: https://developers.google.com/tech-writing/one/active-voice https://developers.google.com/tech-writing/one/active-voice 3: https://developers.google.com/tech-writing/one/short-sentences https://developers.google.com/tech-writing/one/short-sentenc...
- pdr2020 7y agotenets, not tenants.
- bpatel576 7y agoadded a lot of value there
- roryokane 7y agopdr2020’s spelling-correcting comment indeed didn’t add much value, but as it was three words long, it also used up very little time and attention. I think such spelling-correcting comments don’t deserve the criticism you implied. The (minor) benefit of preventing mattlutze from making that particular spelling error in the future was well worth the (minor) effort of making them read a three-word comment.
- soneca 7y agoFor me, a non-native English speaker, it added value. It is not a common word, I didn't know, and the way the GP included it was explanatory. Having "tenant" there would be very confusing, now, I just learned one more interesting. In a post about writing, that's even on-topic.
- graycat 7y agoTeaching of writing has long been mostly about teaching how to write belle lettre. Some of the lessons there can also apply to technical writing, e.g., have in mind and track the reactions of the intended audience. E.g., the script writers for good movies, along with the director and actors, etc. do well having in mind, "tracking", and bringing along the audience, e.g., in what appears to be relatively technical content for movie audiences, the movies Star Wars. So, e.g., anticipate the audience reaction enough to see that they won't get lost and give up. But let's set aside belle lettre, courses in "creative writing", etc. and move on: It turns out there are some technical fields that have long had essentially their own techniques of writing. The writing in those fields is especially good on precision. The better writing examples from those fields can serve as good examples for maybe nearly all technical writing. IMHO, from my experience, some of the best examples include: o The original Kemeny-Kurtz documentation on their programming language Basic. o McCracken's documentation of Fortran. o Any of the freshman college physics books by Sears, et al.. o Any of the best freshman college calculus books. o IMHO, D. Knuth's The Art of Computer Programming. One way to make some progress on doing such writing is to take a college course in abstract algebra where the homework is to write proofs and where the teacher reads and corrects the writing style, technique of some of the homework. For a student who was taught writing Belle Lettre where often ambiguity is desired and precision is not, an abstract algebra course can be a good step forward for technical writing.
- breckenedge 7y agoI graduated with a BA in English with a Technical Writing concentration 15 years ago. I did the job for a few years and, honestly, it sucked. At best, I was treated like an idiot by developers. Developer aloofness seemed much worse back then — they were never wrong. I was always at the end of the software development cycle, so there was never enough time budgeted to do good work. Management couldn’t decide if I was a tester and a writer, so I often had to fill both roles. The rapid nature of software development today is great for users and developers, but lends itself to rapidly expiring documentation. I did the job long enough to teach myself software development. I switched over to being a software dev ten years ago and have never regretted it. Entry level pay as a software dev was better than experienced pay as a technical writer. I have been asked to write documentation, and I’m glad to do it — just not as my primary duty.
- hnarn 7y agoYour comment makes me think that writing primary documentation should always be the job of developers, with time dedicated for the task, and technical writers can do the polishing and categorization that will likely be necessary for it to be published. Being the only one responsible for documentation while not being a developer must be a nightmare.
- CraigJPerry 7y agoYeah in practice there’s just no other way in the places I’ve worked. The problem I’ve encountered still though is getting developers to estimate sufficiently to give that time. Developers massively underestimate (myself included).
- lonelappde 7y agoThe problem is that you are estimating instead of producing and measuring. Just take the time and succeed or fail. Don't estimate it
- Viliam1234 7y agoIf you have waterfall, there is usually not enough time to make the product itself, and documentation is much lower priority than that. If you have agile, in theory all developers are replaceable. In reality, a few have writing skills, but most don't.
- polcia 7y agoWhat do you think, technical writing should be included in the daily job of engineers, or is it ok if the company is hiring people with some low technical skills/experience in favor of some target-language-Bachelor-of-Arts students to do these tasks?
- therealdrag0 7y agoI think it is an area of work that (given a large enough company) benefits from having dedicated owners. Engineers have too many other things pulling at their strings, whether it's deadlines or just code they 'rather' be working on. Some devs will take interest to documentation but most wont. Most seem to just do a single mind-dump and call it good, no better than the college essay they got a C on. There's also real value in having someone own the organization of the writing.
- xaedes 7y agoI am very happy with (technical writing) experts helping with their expertise. That is how I want culture to see their role. Maybe a bit over-simplified: SW-Devs talk to the machines, Doc-writers talk to the people. If you can't make the machines understand what you want it to do, you fail. If you can't make the people understand what to do with your precious developed system, you fail.
- sandGorgon 7y agoThe best i have seen is the economist style guide - http://cdn.static-economist.com/sites/default/files/pdfs/style_guide_12.pdf http://cdn.static-economist.com/sites/default/files/pdfs/sty... the US Army writing style guide for leadership is also pretty good - https://www.esd.whs.mil/Portals/54/Documents/DD/iss_process/Writing_Style_Guide.pdf https://www.esd.whs.mil/Portals/54/Documents/DD/iss_process/... The examples here are very very good.
- combatentropy 7y agoPage layout matters, and Google's has become cluttered. For example, https://cloud.google.com/sql/docs/postgres/private-ip https://cloud.google.com/sql/docs/postgres/private-ip It's so busy I've been opening the browser console to delete sections: the fixed header over 100 pixels tall, the left-column site map, the right-column page map, and the footer. This is what happens when you let Marketing design documentation. I believe part of the problem is also the font. Roboto is okay for a user interface. For prose I prefer serif. My favorite page layout: http://www.linfo.org/ http://www.linfo.org/
- wallstprog 7y agoFrom "Zen and the Art of Motorcyle Maintenance" (https://archive.org/details/ZenAndTheArtOfMotorcycleRepair-RobertPirsig/mode/2up https://archive.org/details/ZenAndTheArtOfMotorcycleRepair-R...) > "But they’re from the factory," John says. > "I’m from the factory too," I say "and I know how instructions like this are put together. You go out on the assembly line with a tape recorder and the foreman sends you to talk to the guy he needs least, the biggest goof-off he’s got, and whatever he tells you. ..that’s the instructions. The next guy might have told you something completely different and probably better, but he’s too busy." > They all look surprised. "I might have known," DeWeese says.