I am growing more and more frustrated with using Confluence to export user guides for my company. Firstly, when exporting, the formatting goes all completely off. I have text alongside images in Confluence and when exported to html all this formatting goes out the window. Search fields don't appear in html exports and neither do page trees. I also have a load of videos that I had in but now had to take out as I found out that Confluence does not work with Vimeo any more. Is there anyway to fix these problems?
I'm new to tech writing. I'm starting a project tomorrow. The lead will give me a run through of the software processes that need to be documented. Typically, how do you guys take notes in this situation?
At the moment, my plan is to screen capture the walk through via Google Meets + take notes.
Another idea was to take notes via flow chart software, combined with Google Meets capture?
Obviously, my concern is accuracy without sacrificing speed (too much) - though the former is always the priority.
Just curious as to what you guys find best for taking notes in a 'sitting in a room and being shown a process' scenario.
I'm starting to develop arthritis in my hands, which makes typing quite painful (but very doable infrequently, and when necessary), so I'm wondering if speech recognition is a viable option to get through the bigger chunks of "writing" even if structuring etc. still requires me to be hands-on.
Can you recommend software (especially structured document editors for docbook etc.) that work well with speech recognition?
I am an in-progress English major who wishes to become a Technical Writer upon graduation or even before I graduate so I can finally become independent financially.
I wouldn't consider it an absolute dream job as I have no career passion at all, but reading up on it a lot, I am really attached to what the role pertains to doing.
My issue: I have read lots and lots of Reddit articles saying "portfolio this" and "portfolio that". More specifically I see, "get a job somewhere (retail) and document a product from that job site that you know well". I understand but HOW. What standards? How does the portfolio look? What is the document supposed to look like format wise?
I understand that the goal is to take technical jargon and turn the jargon into baby words for the audience to understand better but how do I do that and how is it supposed to look, sufficient-wise? Examples would help a lot.
I don't know exactly how to start "building a portfolio".
I'm asking here to get real insight from actual tech writers.
Parametric Press enables its readers to control how much information they see via a slider that has 4 options: "TL;DR", "Essentials", "Highlights", and "Everything". My blog post below explores whether this feature would be useful in documentation. This might be a useful feature if your audience is split between beginners and experts. For example, suppose you got feedback from beginners that your tutorial didn't include enough context. So you add context. But then the complaints from the experts roll in. "Why are you making me sift through the basics? Just tell me what to do." This feature could be a way to make both audiences happy. In the post I also show that it's possible to measure how much aggregate time users are spending in each mode in order to gain some insight into whether your readers generally prefer more information or less. On the writing side, it seems like it'll cause a noticeable amount of extra work for writers, because you have to mark up a lot of content and mentally classify the priority of all of the content. Also, does anyone know of any case studies or research on this topic? I'm pretty sure that DITA people have tried this approach and concluded that it's not worth the effort, but my search came up empty.
I am a third year English major with a concentration in Technical writing. I have had to write so many citations and there are two things that always surprises me when helping other English majors and non-majors. One is that college-aged students think they can still use bibliography generators and the other is that people do not know about this site. Hopefully, this can help some people out there. As many of us know, bibliography generators are often times not the best so this site gives countless examples of anything you could need for a citation and is extremely up to date. This can avoid plagiarism issues as well as making it super simple to do your own bibliographies with clear outlines and examples. I always share this with my friends and thought I would share to help out some others who might appreciate it before they fall victim to buying another garbage style guide! (Most of us probably have too many anyway...). Just a college student trying to pay it forward...
I'm starting a technical writing internship on Monday. I'll be under the supervision of an actual technical writer, but I wanted to prepare myself a little more before starting. The job description states that one of the key responsibilities is to "adjust key operating procedures used in the manufacturing process." I'm a junior in my program, so I've written and edited many things, but I have yet to work with anything similar to this. The closest I've gotten is editing a few engineering students' papers on technical subjects.
The job description also states that we will be working with SMEs to gain the necessary knowledge. So, my question to you lovely people: How can I prepare myself to work with operating procedures? I don't know the specifics of the manufacturing process (yet), or I'd give a little more context. What should I expect? I know I'll have to rely on the technical writer overseeing me, but I also want to be able to contribute. If anyone has any similar experiences, tips, or warnings (lol), please let me know!
Recently I discovered that a supposed documentation "best practice" may not actually stand up to scrutiny when measured in the wild. I'm now on a mission to get a "was this page helpful?" feedback widget on every documentation page on the web. It's not the end-all be-all solution, but it's a start towards a more rigorous understanding of what actually makes our docs more helpful.
Edit: Sorry, I'm realizing now from the comments of mainhattan and herennius that my mention of "best practices" is too vague. I'm calling out our entire approach to "best practices" into question. Some of the examples I provide are "use the active voice", "shorter docs are better", "avoid fancy words", "do not inject opinion", "task-based architectures are best". But these are just placeholders. Replace them with whatever "best practices" you adhere to. The main idea is that I want us to start working together to prove that these practices actually measurably improve the perceived helpfulness of our docs. If they don't, I want to find out what strategies actually do measurably improve our docs.