Copy pasting a comment I wrote earlier today in another thread - no experience with Codecademy personally, but this is how I recommend anyone new or pretty new to coding to learn:

If you are actually looking to learn to code (zero advice or judgment as to whether you should), start with https://www.freecodecamp.org/. They will teach you HTML & CSS along with some accessibility standards. You must treat their course like a playground rather than completing each lesson and moving on asap!!! If you can do that, their progression is absolutely lovely, and you'll have a really solid background. As a bonus, you'll get great examples of tech writing as you go, because their explanations are awesome! The downside is that they do allow you to progress super fast without learning anything, if all you do is try and breeze through everything. (The upside to that downside is, if you already know stuff, you can in fact breeze through that part lol.)

After you get past HTML/CSS, you can if you want start learning some JavaScript; at this point I'd recommend saying "fuck that" and switching to Python from https://learnpythontherightway.com/ because JS sucks and Python is a much better scripting language, unless you have a deep need to build client-side code on websites for some reason (you don't). But FCC's HTML/CSS is a much gentler introduction than this Python course, so regardless of what you wanna do, I'd say start with the HTML/CSS progression & then move to Python.

Once you're comfortable there, do whatever you want & build stuff :)

Everyone everywhere uses Word. Even if they don't use Word they use something built to mimic it almost exactly. It's inescapable.

Set yourself apart from the 99.999% of everyone who creates headings in Word by highlighting the text and selecting "Bold" and then changing the font size. Learn how to use Word - styles, templates, formatting, headers, footers, table styles, etc.

As for authoring tools, there are a number to choose from. To be honest, you should be able to pick up the basics of any of them fairly quickly. For the most part they're all WYSIWYG editors with some additional features.

I'm using Flare at my current job, and my only exposure to it before I started was downloading the free trial and working through the included tutorial. If I started a new job where they used RoboHelp I'd do the same and just figure the rest out as I went.

Ah, okay, so not everything is through an Agile process. 1 and 2 products make sense in an Agile environment. There's some more bandwidth there to work on more products if they aren't under Agile. Here's a great book to help you out: https://www.splunk.com/en_us/blog/splunklife/the-product-is-docs.html

I'd use it as a reference point to your manager of how world-class documentation teams operate.

Using the Microsoft manual of style is a good way to be consistent in your software interface terminology.

Microsoft Manual of Style https://www.amazon.com/dp/0735648719/ref=cm_sw_r_cp_api_glt_fabc_TV1BYJ7FWZX8DM414Y6S

If you are actually looking to learn to code (zero advice or judgment as to whether you should), start with https://www.freecodecamp.org/. They will teach you HTML & CSS along with some accessibility standards. You must treat their course like a playground rather than completing each lesson and moving on asap!!! If you can do that, their progression is absolutely lovely, and you'll have a really solid background. As a bonus, you'll get great examples of tech writing as you go, because their explanations are awesome! The downside is that they do allow you to progress super fast without learning anything, if all you do is try and breeze through everything. (The upside to that downside is, if you already know stuff, you can in fact breeze through that part lol.)

After you get past HTML/CSS, you can if you want start learning some JavaScript; at this point I'd recommend saying "fuck that" and switching to Python from https://learnpythontherightway.com/ because JS sucks and Python is a much better scripting language, unless you have a deep need to build client-side code on websites for some reason (you don't). But FCC's HTML/CSS is a much gentler introduction than this Python course, so regardless of what you wanna do, I'd say start with the HTML/CSS progression & then move to Python.

Once you're comfortable there, do whatever you want & build stuff :)

For academic articles, look at the EServer Technical Communication Library. You should find a good bit of stuff there to get started with.

For the other articles, I can say that I'm always interested to read about what tools people are using, especially if they're NOT using applications like Word or RoboHelp or any of the usual suspects. And if the person is writing about one of those topics, I'd at least like to see an interesting use case or configuration option that I might not have known about otherwise. I also like to read about different workflows, and about any open source related items as they pertain to tech writing, such as using something like Scribus in an enterprise setting.

> Markdown for documentation

If you've ever formatted Reddit comments then congrats, you've used markdown. Or if you've used any HTML then you've done something more difficult than markdown.

> Atom & Github

Atom is just a code editor. You can download it now, set the view to any language you and it'll help you catch any errors that are made. Github is version control software that lets multiple people work on the same project without overwriting each other.

Use this to learn some of the basic git commands and why its used in software development. Create a github account and edit a document using git commands and after a few commits you'll have it cold.

https://www.theodinproject.com/courses/web-development-101/lessons/introduction-to-git

> C++ and Python

You don't need to be a developer to understand the basic concepts behind these languages but you can learn some of the terminology like knowing what a function is and where you can point out an argument. Heck do some basic "into to python course", write the code in Atom and then upload the files to a Github repository you create. You can do that in an afternoon and know enough to not be blindsided in the interview. Heck, show them that you went ahead and created that repo and that'll impress them that you went from zero knowledge to covering some of your first-week stuff already.

I'm 100% from a technical background (math major & currently a developer who also writes rather than a TW) but I would definitely encourage you to take some CS classes! Everyone, literally everyone, feels overwhelmed & confused, just some people hide it better than others, and some people start feeling overwhelmed & confused a bit later than others (mostly due to previous background/experience). (Maybe you notice your classmates breezing through intro CS but dw they'll be crying when they get to operating systems.)

The trick is to find joy in the overwhelming! It's exploration and discovery! Yay! Find friends to learn with! It's soooo much fun to explore entire new paradigms/ways to organize human knowledge, which is like, the same as TW, just, in a totally different way - instead of learning how people think and how to communicate effectively for people, you're learning the structured logic of how to implement best practices of expressing explicit instructions for machines that we've figured out over decades of experimentation (that's really what programming lessons are).

Ok so in terms of actual advice instead of motivational bs, I'd suggest https://www.freecodecamp.org/ - when I was self-teaching I did their HTML class start-to-finish and a bunch of their CSS. Here's a previous comment I wrote about it. If you can get through their HTML on your own in your free time, and you're having fun you should 100% no question get a CS minor. If you're getting through it and miserable, this is a you-question - how much do you wanna stick with it for career opportunities? If you can't get through it, see if you can get help with it, and then go to square one. And if you really can't get through it no matter what, maybe consider a different area of TW.

Yeah, don't spend money on anything* until after trying out FreeCodeCamp. Their curriculum is pretty good; you just have to make sure you're actually learning rather than breezing through. If you don't find yourself learning enough from that then maybe try something else, but this resource is fantastic. It has 0 setup and lets you play around with a lot of stuff, so like if it says "put one element here" you can be like oooooooh what happens if I put TWO elements here in the sandbox, and then do just that, and then it shows you how the output looks in real time; then you can go back and make the one element and get validation that your answer is correct etc. Definitely recommend it!

*If you get everything you need from FCC I'd definitely encourage you to donate to them if you can afford it though!

freeCodeCamp is a great resource for coding and other subjects

The HTML Handbook (freecodecamp.org)

Additionally, they have a YouTube channel with great content and full courses. If you increase the audio to 1.25x or 1.5x, you can do some serious learning in one day.

W3 Schools is another great online platform

W3Schools Online Web Tutorials

The thing with the internet is that there's a plethora of information out there, so you gotta learn to filter what you absorb and find what best works for you.

Hope this helps! Feel free to ask any other questions!

IANAL:

Fair Use has 4 factors you have to consider and it has to meet all 4. Basically - The less you use, the more you change it, if it's non-commercial, and if it doesn't affect the original product - you MIGHT be okay.

> One such factor is acknowledgement of the copyrighted source. Giving the name of the photographer or author may help, but it is does not automatically make a use fair. While plagiarism and copyright infringement are related matters, they are not identical. Plagiarism (using someone's words, ideas, images, etc. without acknowledgment) is a matter of professional ethics. Copyright is a matter of law, and protects exact expression, not ideas. One can plagiarize even a work that is not protected by copyright, for example by passing off a line from Shakespeare as one's own. Conversely, attribution prevents accusations of plagiarism, but it does not prevent infringement of copyright. For example, reprinting a copyrighted book without permission, while citing the original author, would be copyright infringement but not plagiarism.

As I understand it, Credit/Disclaimers are useless unless the content license allows for it (ie. Creative Commons Attribution Licenses) or they are small quotes.

TL;DR - Rewrite it and customize it, since it's commercial it's probably not fair use.

>Stuff on the desktop drives me bonkers.

I used to feel that way, until I discovered Fences. Now I've got a little corral on my desktop for each current project, with shortcuts to the various content and source data folders along with project management files.

I'd highly recommend LICEcap by Cockos (http://www.cockos.com/licecap/). You can select the frame rate, estimate the size of the file, and it's free. Plus it's available on Windows and OSX. I've also used it with some success on Ubuntu using WINE.

GIFs are great, but it can be easy to over use them for every little thing. I tend to only use a GIF when I'm explaining a few points or steps at one ("click here, click there, type there, press that, hit OK" etc).

It is a great tool along the same lines as the Hemingway Editor.

TechScribe used to provide their STE (simplified technical English) checker for free if you request it. I'm not sure if they still do, but it's worth sending them an email to check if you don't already have it.

Our knowledge base is a Hugo static site (free). Docs are written in markdown and managed through GitHub.

When I push changes to the repo, the site automatically rebuilds and publishes -- that happens via Docker/Jenkins. Someone more technical than me set that whole deal up - I just have to know how to use GitHub and Hugo.

Technical Writing Process by Kieran Morgan. This book is my personal favorite. Dry as all get out, but instrumental, especially for me during my first year as a junior technical writer. I have a few more if you like this one.

The Office Lens App is pretty useful to anyone working with designers, architects, or engineers whose favorite design medium is a whiteboard.

If I ask an SME to provide a digital design, I might have to wait weeks. If I can corner them in a conference room, they can draw out the diagram, I take a pic with Lens and then make a digital version myself in an hour or two.

I've also used Lens to take pics of signed contracts, permission slips for my daughter, and various other things.

> Grado

If I'm guessing right, those are more on the low-end of those headphones, correct? I really can't say much, I wear Bose noise cancelling headphones all day every day, and that has been the best $350 I ever spent. I was honestly more surprised to see so many wired headphones as opposed to wireless.

If you're into headphones and manga, there is actually a headphones manga: Mimiyori Harmonia, which is about headphones, headphone technology, and some headphone history, with (of course) cute manga girls.

If there's ever something you wish you could tweak on Greenshot but can't, check out ShareX - it's built on the same source but with an everything-and-the-kitchen-sink approach to workflows and config options. I use Greenshot at home and ShareX on my work machine.

If you want to give them something challenging, I recently had to refer to the ArangoSearch 3.5 documentation and found it to be particularly bad.

This would be too challenging to give to students as a graded assignment, IMO, but it could be fun to walk through and give a few examples of simplifying sentences for concision.

Yes, wordpress.com allows you to host on their domain as WarpSeven.wordpress.com (w=you;d want to use your real name so it looks professional) which is good enough for this situation. You can upload pdfs that others can look at or download.

Cybersecurity without a doubt.

Cybersecurity is always on the leading edge of a lot of things, so I'm not sure why you think you wouldn't learn any new technologies working there. You may be familiar with what they're working on now, but they've probably got things on the roadmap that will keep you busy learning for years to come.

Also, keep in mind that you don't need to rely on your job in order to "learn many, many new technologies." There are so many ways you can do that on your own. For example, you mentioned cybersecurity - install Kali Linux, and start teaching yourself.

Yes, you're on the right track for building a portfolio to demonstrate your skills and knowledge in technical communication.

Portfolios are somewhat relevant depending on the hiring process. For example, some jobs may request a sample of your writing or a product you previously created. Make sure that you have permission from your current/former employer/client before submitting these to a potential new employer or placing on your website.

In the past, I've created my portfolio of original works on a WordPress site. I also keep some of my own portfolio works away from my website for use on individual applications. It depends on what an application is looking for. I have used some of my own portfolio examples to apply for Graduate School too. Just make sure they are print-ready, such as exporting your examples into PDF so you're not scrambling to find a font, linked image, have to recreate it from scratch, or end up with embarrassing layout errors. (I've seen the whole show of hot messes, including the Meta Description of files if it doesn't get stripped out. Plus if it's a .docx, I'll inspect Word Styles usage in the document as well.)

Your portfolio can be as simple as a free WordPress.com website. You can pay a bit to get a custom and unique domain. I consider paying for a website like an investment to market yourself. Also having a website is an accessible window to demonstrate to people looking to hire you that you have the digital know-how for using your resources.

Best wishes on your career endeavors!

Yeah we've built tons of projects with those!

Don't want to come off spammy, but my colleague wrote a review of the top 5 with a ton of technical information about them and their latest updates. It's a bit of a time saver over researching each one through Google (which is what he was doing when he decided to just write the damn thing).

https://snipcart.com/blog/choose-best-static-site-generator

More to your point though, yeah they are super impressive. The one I'm surprised you didn't mention was Gatsby. That's been gaining tons of steam over the last half year or so!

My take on "videos vs documentation" is that videos are good for initial introductions (i.e. new user training) and documents (or html help files) are good for reference material.

For example, it may be easier for new users to comprehend the overall basic functionality of a piece of software through videos (normally in 5 min chunks). However, we cannot expect users to retain everything from the video the first time they watch it and they often do not have the time to return and re-watch a video. Videos are also very difficult the "search" through. This is where the document comes into play.

Another thing about videos (as I am sure you are aware) forward maintenance on them are a beast. They are often very time consuming to create and update.

Also, how long have these videos been out of play? Have there been a number of requests to update them from users? Or, are the considered "nice to haves?"

What about a different technique? For example, maybe you could use an animated gif depicting the concept discussed. Furthermore, instead of embedding it in th actual page.you could create link/popup. That way users who want to read and move on can, while users who want to see it in action can.

Also, using a program like LiceCap significantly reduces the overhead to the point that creating the animated gif is as simple as creating a screenshot.

Point being is that before you put a ton of work into reworking a number of outdated videos, ensure that doing so is the best solution to your problem.

This is what Pandoc was created for. You can write your documents in Markdown and then use Pandoc to convert them to the formats listed. You'll have to do some work tweaking the outputs to your satisfaction, but it can be done.

I will note that if your documents rely heavily on tables, look at using reStructuredText instead of Markdown. Markdown's table support is shit.

> I'm assuming you work for Red Hat? That's cool. :)

That's right, and it is cool :-)

> The $ means a normal prompt, and # means super user or root, right?

Exactly. And if the current directory, the current user, or the specific machine matter for the command (which they rarely do), we could specify it like this, modifying the default Bash prompt:

/some/directory]$ command [user@system /some/directory]$ command

> How do you format the text if it includes a variable?

A hotly debated issue! Some of our documentation uses italics for that (variable), other places use pointy brackets (<variable>), capitals (VARIABLE), or the shell variable syntax ($variable).

> if there is a prompt to confirm a selection, would you include that in instructions?

I'd say it depends on the prompt. Some programs of that kind make it very obvious what you're supposed to type or press. For example, if a program stops to ask you Do you want to proceed? [yes/NO], I think it's enough to document it as "Type yes". If you want to be safe, I'd mention Enter in the same sentence: "Type yes and confirm by pressing Enter."

> Any chance you have a public style guide for your documentation?

Our main style guide is the IBM Style Guide, which we've been using since long before the acquisition. It's pretty comprehensive. You can buy it as a book:

https://www.amazon.com/IBM-Style-Guide-Conventions-Writers-ebook/dp/B005Z09FOC

Then we also have a public supplementary style guide:

https://redhat-documentation.github.io/supplementary-style-guide/

Definitely check out [Write the Docs](writethedocs.org).

I think some good books to pick up might be Docs like code and Modern Technical Writing, especially if your company uses git and github for code.

Thanks for excusing the typos in my original post. It's hard to post well on a phone.

Regarding the cart before the horse, I agree mostly with that concept. But I do believe a good professor will present you with theory as well. For example, two critical points of technical writing are:

1. Being brief, direct, and clear. It's editing that's essential to this skill. It would be worth picking up Strunk and White's "The Elements of Style." It's a well regarded, inexpensive style guide with practical tips.

2. Recognizing that you are writing for the benefit of the audience. You are translator, but the audience's need is key. For example, I've heard recipes used as an example. Consider a chocolate cake. If you wanted to write down your recipe for chocolate cake, (or chile, or an omelet, etc.) you would write it differently for a professional chef, a college student, and a 6-year old. At the end, each may have the exact cake that you baked yourself, but there's no way you'd use the recipe intended for the professional chef for the child, and vice versa. It just wouldn't work. The child's may require illustrations and insistence on parental guidance for example. The professional chef's might use terms only an experienced cook would know. So, you're getting to the point best by addressing the information to the audience.

How do you do this? First, find out what the audience needs to know, then consider what you know and apply your knowledge to the need.

If you haven't read The Elements of Style cover-to-cover, do it!

The Handbook of Technical Writing has been a helpful reference for me over the past couple of years. I wish I had found it sooner.

You could possibly talk about the importance of the master / main branch and how changes are merged into that from others. The concept of collaboration using pull requests as good as well, if only to hammer home Git as a tool to bring changes together.

I needed to learn Git about 18 months ago and I started with this book. It's free in its Kindle form and I thought it was excellent. You can work through it in a few days and do any exercises on a computer without needing web access, Github or any online remote repositories. https://www.amazon.co.uk/Rys-Git-Tutorial-Ryan-Hodson-ebook/dp/B00QFIA5OC

I hope that helps, but I'd be really interested to hear the comments of other Git users.

I've used Northbooks (https://smile.amazon.com/gp/product/B013VPDJLW/ref=ppx_yo_dt_b_search_asin_title?ie=UTF8&psc=1 with their nice Kraft cover, and Moleskin in various sizes (Costco used to carry them online) which come in various colors including black. I've seen Moleskins most recently at Staples where the stitched ones came in a 3-pack.

I've also tried out various knockoffs of the original Traveler's Notebook in multiple sizes, you can find some lovely ones on Etsy for a reasonable price. Most are definitely feminine (since women buy some high % of the things on Etsy) but you can find solid covers. A lot of fountain pen users also love Traveler's Notebooks, so many sellers use decent paper.

For technical writing improvement, I definitely second “The Product is Docs” and I would add “Nicely Said: Writing for the Web with Style and Purpose (https://www.amazon.com/Nicely-Said-Writing-Purpose-Voices/dp/0321988191).

For general writing, I have to go with “On Writing Well” by William Zinsser and “Writing with Clarity and Style: A Guide to Rhetorical Devices for Contemporary Writers” by Robert Harris.

Best of luck with your studies!

Try this.

There may be other books out there. I forgot the other title but also look up books that go over people you don't like dealing with too.

I liked Writing and Designing Manuals and Warnings by Pat Robinson.

https://www.amazon.com/Writing-Designing-Manuals-Warnings-4e-ebook-dp-B008KZBV7S/dp/B008KZBV7S/ref=mt_other?_encoding=UTF8&me=&qid=

It depends on the license of the image you're using. Some licenses have few or no restrictions, some licenses prohibit using an image for a profit, some mandate that you have to give attribution to the original creator, and some mandate that you can use an image but all derivate works have to be shared using the same license.

The easiest way to deal with it is to put anything you made behind a password and then share the password with any potential employers. At that point it's not being publicly shared and so you can do whatever you want.

Using this as an example https://stripe.com/docs/api/skus/create

tldr; Attributes are for looking only, parameters are for editing.

An attribute is a value you can look at. You cannot change it. Notice on the linked page attributes are for the 'SKU Object'. The object is data you received from Stripe, not data you're sending to Stripe.

A parameter is a piece of data you can edit to send data to Stripe. On the linked page under Create a SKU, the cURL Post is what you send to Stripe. Stripe then takes this data and your entered parameters and creates the SKU.

The response example in the Create a SKU section is another object you cannot edit and contains attributes.

-=-=-=-

Attributes and parameters are very common, but programmer-y terms. If you're writing for programmers, I think this is acceptable. If not, different names should be chosen that fit the scenario.

I would not use 'field' though. Field to me implies a place I can enter data on a form. Think of a webpage where you put your name in the Name field. At least is this example, it's not a form.

My comments will really only relate to tech writing in the software industry, since that is my background.

Learning to read code is probably the most valuable (non-writing) thing you can do. Second, learn to use a UNIX-style terminal to interact with web APIs.

I don't recommend getting a certificate. At least in my experience, credentials don't mean anything. At good companies, people generally only care about what you can do.

The traditional "user interface" (UI) subset of technical writing is probably only going to shrink going forward. The trend in product development that I've seen is to work with UX designers to attempt to make the interface "intuitive" so that people can just figure things out for themselves. Also, there is generally no UI documentation for mobile apps.

The good news is that software is eating the world, and as such the fastest-growing tech writing subfield is probably API documentation aimed at a technical audience, meaning web APIs, mobile SDKs, etc. I'd recommend focusing your efforts there if it aligns with your interests.

Google's Season of Docs.

https://www.freecodecamp.org/news/cracking-google-season-of-docs-2020/

I haven't done it, but it seems like a great way to build a portfolio and not have it behind a NDA.

Otherwise, I would look into growing with a company, or look for any junior technical writer role and deal with the pay cut for a while. After a year working with the tools, you should have enough of an understanding to get into roles.

I found this LinkedIn thread where it seems kinda split 50/50 in terms of opions.

The salary opportunities seem much higher for Business Analysts. So, although it isn't the only reason to take a job, it certainly is a consideration for me.

> This very documentation site is running on a Gatsby.js front-end, connected to both Ghost and GitHub as content sources, hosted statically on Netlify with dynamic serverless functions powered by AWS Lambda (like the feedback form at the bottom of this page). It’s a brave new world!

https://ghost.org/docs/architecture/#static-site-generators

That's good to know, I'll look into Confluence. Thank you!

I posted this on /r/Manufacturing, as well, and one of the programs recommended to me was Dozuki. It looks like it encompasses some of those features that you're missing.

I mean a combination of Markdown (could also be AsciiDoc or ReStructured Text), Github, and Github Pages. I've never used it, but it seems to be very simple to get up and running.

Your content can be made part of the CI/CD pipeline and then ported to something like a static site generator, another place/CMS, or to Github Pages.

Microsoft, Google, and ironically Adobe, among others, author in Markdown.

I'm a bit late to the game, but my tip would be Blender - it's actively-developed, well-known, open-source 3D animation software. I recently did a large coding project (for university) with it, and noticed that the documentation could definitely use a tech writer's touch (I regret not making notes of the deficient areas as I encountered them!)

Some of the docs are a Wiki, and there is a manual, both of which focus on using Blender's GUI to make 3D animations/games (there is also a Python API but this is documented differently). Unfortunately there are many areas in the manual that still have TODO as the only content.

From my experience, the community using Blender is very active and they would welcome some help. Also the software is well-established and fun to play with.

This might help you self-evaluate and think through tech writing career options: https://www.notion.so/amrutaranade/Is-Technical-Writing-the-Right-Career-for-You-3085604c58ad453086331cdabf1953c5

Don't leave out Libre Office. For most documents it's fully compatible with the MS equivalent. Since it's free, there's no reason not to experiment at least.

It should support most docx templates, etc.

Open Source!

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.

I'd suggest taking a look at github pages. With it you can easily create a website using either markdown or HTML. Markdown is a simple semi-structured language, but for simple content, it's more than adequate. An added benefit is that this will give you some experience using a version control tool.

I wouldn't focus on any particular tool because you never know what your employer will prefer.

Check out https://squoosh.app, a tool built by some of my teammates on Google Web DevRel.

https://images.guide by Addy Osmani, another one of my teammates, can give you pointers on a bunch of different tools for resizing and optimizing images.

I’m not sure if Word supports SVG, but if it does and you’re working with illustrations, that’s a way to maintain resolution. Read up on the difference between vector and raster images to learn how this works.

Do you know why they settled on that resolution? To keep the size of the MS Word files small, perhaps?

I have to a limited degree. Like everything in technical writing, it is not the end all be all technique, but it does come in handy. When I do use animated gifs, I use LiceCAP .... http://www.cockos.com/licecap/

This can be done with Confluence - you can have licenses for everyone who will need to edit the content, and then others can view it - they won't be able to edit, or even comment, just view. cPanel does something like this for their documentation.

After that you can put it behind some kind of access control so only registered users can view it.

Of course, you could also do something similar with a tool like MediaWiki. The user interface for editing won't be as pretty, but if you're dealing with developers and project managers they should be able to figure it out fairly easily. If I had to do this on a budget this is the route I'd take. And again it would be just a matter of putting this behind whatever access control you needed.

FYI, the link to your portfolio site doesn't work. There doesn't appear to be an A record (meaning the hostname of mila-carter.com doesn't actually point to an IP address in the DNS record).

http://viewdns.info/ismysitedown/?domain=mila-carter.com

Another benefit of HTML over PDF is analytics. If your HTML-based help system is on a web server, you can get a ton of data about usage, particularly if you can use Google Analytics. The only statistic you can get for publishing a PDF is the number of downloads.

EDIT: clarification

Have you tried Simple SaaS Knowledge management solutions like Document360?

It has been working best in many enterprises where they have tins of documentation to done and all have multiple authors contributing the documentation.

Workflow can be easily managed with restricted user access based on roles. This will avoid spamming the document. Also looks like you have your current documents in word, it also supports word export and if the migration is at large dedicated support is provided.

To automate and enhance productivity it supports many in-built 3rd part tool integrations and via Zapier.

Take a trial to evaluate Document360

> your involvement is more of the flow and language accuracy than the actual steps?

For the internal documentation, yes.

For the public facing product documentation I have set up a process with the development team for them to notify me about product changes. It usually starts with a ticket, I research the new feature or improvement, write the needed documentation, and send it back to the specific development team that can review and give me feedback.

> Do you also transition their document to a universal format?

I wrote a style guide for our company documentation and have given "Dev Academies" as well as a short documentation course to new developers when first employed. But for the most part, the different teams manage their own internal documentation and it is up to them if they want to follow my guidelines. The public documentation tries to follow them as strict as possible as I am the gatekeeper.

> what is their storage process

We use Atlassian's Confluence. Though if we are storing a file over few mb... it is usually stored in Box and linked.

Forget RoboHelp. It's expensive and, IMO, overly complicated for what you want to do.

For your purposes--a basic help system, relatively simple interface, try HelpnDoc. http://www.helpndoc.com/ Free, and pretty versatile.

CockroachLabs is looking for a Senior Writer, and it's full remote, so you could live where you wanted in US/Canada. https://www.cockroachlabs.com/careers/job/?gh_jid=2180996

With Google docs, you can provide a shareable link, and set that link so that anyone with it can either view, comment, or edit. Obviously, the view option is what you want. It looks like you can do this with an entire folder too.

> When I decide to publish it as a webpage publicly, it throws off the entire layout

Are you publishing stuff as a web page from Word directly? Word is ~~shit~~ not good for this kind of thing. In your case, I would get a free WYSIWYG HTML editor like KompoZer, copy your content from Word into a plain text editor like Notepad to remove all of Word's inline formatting, and then paste that into KompoZer and reformat it. That will give you an HTML page that will look like what you expect it to look like.

If that's not what you're doing you'll need to provide more detail as to the process and what exactly is going wrong for anyone to be able to help you.

I think if you go full-bore bootcamp, you might as well just become a developer at that point. The money is better and there are more jobs available.

For me, it was a years long process of doing slightly more and more technical projects. I did lots of Ruby on Rails tutorials. Messed around with a book on Objective C for iOS app programming. Picked up Nodejs to collaborate on some tooling being used to create API documentation.

I think a self-paced course like The Odin Project is as good a place to start as any. You don't have to do all of it, but getting to know your way around websites, web services, and the architecture behind SaaS products will serve you pretty well.

Honestly, if I had gone full bootcamp in my 20s, I probably would have just become a software engineer. Instead I made the move into management at the same time I was getting more technical, and ended up choosing that instead as a path forward in my career. It was a matter of opportunities, though. I had a 12 month plan to become an engineer that was disrupted by a layoff. Instead I found myself at a new company and then in a leadership role that got me to where I am today.

> It's not because I don't care about the work, but I seem to just not communicate it properly to them?

Well, part of that is why you have a technical writer/editor. They're paid to be exacting.

That said, having to rewrite over and over is frustrating. A few thoughts:

1. When you sit down to write something do you outline it all? I find that when I think I can just put some text on the screen it never just works out. Things always, always, always go easier when I have an outline. Even if its just a simple list of things I want to address.
2. Use shorter sentences and an active voice. Use the Hemingway Editor and try to get all the issues your text flags down to zero. Practice that way and eventually you'll get a feel for it.
3. Temperment can matter. I'm perfectly happy to write everything for someone if I can. Now I'm not a tech writer at my current company and the one who is instead wants a lot of content up front. Might be worth asking if they'd prefer you to just have the ideas/outline and they do the content. It depends on the workflow and the role of the writer. I know I'd rather just sit with you earlier and get it right the first time rather than go back and forth. Maybe they're the same way.

I haven't come across it. All my writing coaching just came up organically through school or working on assignments.

​

But one tool that might work in the interim is the Hemingway App.

​

http://www.hemingwayapp.com/

​

It's basically a tool that finds passive voice sentences and adverbs and asks you to rewrite so those disappear (mimicking the writing style of Ernest Hemingway, famous for his dry and direct prose).

It won't solve every problem but is useful for those things.

So Markdown is essentially your formatting programming language that you use in Perl? Why isn't there something you can use with simpler "Word style" functions like pushing a button to italicize i.e. what is the advantage of using this over Word?

In their example post they have:

![Screenshot of Movable Type 'Text Formatting' Menu][tfmenu]

But there is no link to a screenshot.

Pandoc makes a document web ready? Converts it to html at the push of a button or converts from one format to another?

Is most of your writing published online, no paper guides?

I'm a long time Linux user. I use Geany and at one time Bluefish. Both editors are cross platform although I don't use Windows.

I use Geany to support my blog and to some extent Dokuwiki at work.

There is Publii - https://getpublii.com

It has WordPress like GUI and internal Logic. With WISYWIG editing and some markdown support too.

The downside - it's a single user system, there is an unnatural way to make it multi-user-friendly but only as a workaround.

Here is an overview of what it does and how it does it

I'm dealing with tutorials and "How to" articles and this thing works for me, however on my team projects there is no chance I would introduce tool, I barely made my teammates learn WordPress publishing :(

I’m a big fan of Flare, but the learning curve and cost a a bit steep. Illumina uses Flare for their documentation, so you may want to look there. For non-Flare output, have a look at the gallery for Hugo.

Asciidoc can support this with it's include macro. Also, would could pair asciidoc with hugo for the site generation part which include asciidoc support.

Sure, learn to code a bit if you like. Depends what you mean by 'code' though! In any case, I've been very impressed recently by a static website generator called Hugo that I'm sure could do with some help. (Disclosure: no connection whatsoever with the Hugo team) https://gohugo.io/

I was suggesting you get one and work on a project that interests you just for the experience. Take a look at building a RetroPie, Plex Server, or a torrent box. This will give you some exposure to linux, terminal commands, and other interesting stuff. Sure, you could turn around and write a guide on how to do it, too.

To get a job though, here's exactly what you need to do:

1. Write your resume. Tailor it specifically to each job you're applying to. If you're a writer, have a bachelors degree, and have a tech-writing cert, I'm sure you'll meet SOME of the job listing's requirements.
2. Build a portfolio. Like I said before, create a website and post your work there. Lots of resources online for how to do this. Make sure your samples are strong. They should be your number 1 focus. If you really want to demonstrate some dev skills, look into generating your site with Jekyll and hosting it on GitHub pages.
3. Apply to jobs. Don't worry about the requirements. Just apply. It's a numbers game. It might take time.

Not for much for publishing but if you already have that setup and want to bring collaboration to content creation, I can recommend: https://ckeditor.com/collaboration/

I've used TextExpander for some of the things you mentioned. There are a number of similar products on the market.

At a previous job, I had a TextExpander snippet that would insert the document template I had created in Markdown in a text file, along with the CSS. I also had the inline HTML blocks for code examples, warnings, tips, and the Markdown formatting for images that I could insert into a document. Basically, anything I had to type on a regular basis I had a snippet for in TextExpander. This saved me a lot of time over the course of my day, because I could just type in the abbreviation for the snippet, and TextExpander would insert the rest of the text automatically.

ESSENTIAL TOOLS? Relevant to most types of technical writing?

Basic Screen Capturing:

• SnagIt (or one of a dozen free tools)
  

Basic Authoring:

• MS Word or Google Docs
  

Basic Diagramming:

• Visio or Lucidchart.com
  

Basic Repository:

• Confluence

​

IMO:

Advanced Authoring:

• FrameMaker
• Madcap Flare

Also check out this book by my colleague (and a large cast of coauthors): Docs for Developers: An Engineer’s Field Guide to Technical Writing

I've only just started reading it, so can't recommend it personally, yet, but it looks promising.

I've been using this monitor stand for 5 years, it's holding 2 23" 1080p monitors, as part of a 4-monitor setup; the other 2 are 27" 4K monitors that sit flat on my desk. No complaints really, it's a monitor stand and it works and it wasn't expensive then, looks cheaper now.

Mechanical keyboard - I bought one from https://www.wasdkeyboards.com/ with Cherry MX Brown switches - they are decidedly not top-of-the-line, but pretty affordable as far as custom mechanical keyboards go. No RGB lighting or anything, their keycaps wear out pretty quickly (I type a shitton though tbf) & I had to replace after about 3 years or so, cos the coating was coming off and some of the keys were starting to get uncomfortably rough to press. That said, again, affordable & the switches are fine so can't complain really, cos replacing just the keycaps isn't that expensive.

You want a proper keyboard?

Das Keyboard is a piece of Das Nonsense— designed by Americans built in china. Loud. Flashy. And meh.

Cherry switches? More like chickens in a henhouse.

The only real option is the Realforce Topre 55 g actuating keys. Very distinct sound. Designed and built in Japan, not loud, but not silent (although they have a silent option). They keys are heavy but when they purr, they purr.

Don't believe me?

Here:

https://www.amazon.com/Realforce-87U-Tenkeyless-55g-Black/dp/B00MV84Y2Y

Microphone:

Rhode Broadcaster.

Displays:

Wacom Cintiq 24. 99% adobe accurate RGB. Touchscreen. Over 8000 points of pressure with the stylus, can create and recreate any line or dot I want. Super responsive. Perfection divine.

2 additional horizontal displays, and 1 vertical.

Smartphone:

Google Pixel 5.

Tablet: a newish Apple Ipad.

Headphones:

Sennheiser HD660s— you'll thank me later.

Pen:

Conway Stewart Fountain Pen.

Paper:

600 x 800 mm 40 lb paper that goes under my keyboard.

Rhodia Notebooks.

Webcam:

Shit.

A TW colleague of mine wrote <em>On Fragile Waves</em>, a fantasy novel. There are other famous technical writers who are/were novelists as well, such as Amy Tan and Ted Chiang.

It's a mixed of bad and okay reviews, so I'm not sure myself.

Technical Communication Today (5th Edition) https://www.amazon.com/dp/0321907981/ref=cm_sw_r_cp_api_glt_fabc_EAJD2TQCSHGABC8DQD83?_encoding=UTF8&amp;psc=1

It sounds like you’re a little unclear on what technical writers do and that is causing some undue stress.

Technical writing = / = writing for tech. Technical writers have been around for decades and write in industries as far ranging as food, agriculture, manufacturing, corporate human resources, etc.

The job of a technical writer is to take information provided by subject matter experts who are not necessarily great communicators (e.g., mechanical engineers, software developers, chemists, lawyers) and use it to create something meaningful, understandable, and well-organized in a fashion that the target audience can understand it as easily as possible.

Yes, you can certainly be a technical writer that creates software documentation for a professional audience (I am), but you can also be a technical writer that creates instruction manuals for kids’ toys, or a technical writer that drafts standard operating procedures and warning signs for industrial workers.

Back when I first entered the world of technical writing I attended a technical writing workshop taught by Pat Robinson and got a copy of her book. It looks like it’s still updated and republished regularly. It’s somewhat geared towards the consumer products and manufacturing sector, but does a really great job of relating the thought processes and core philosophies of good technical writing. May be a good place for you to start.

First of all, nice work! Factory technical writing gigs have always been a personal favorite of mine. There is just something about the tangible nature of the products or material that makes it easier for me to communicate the essentials.

In terms of specific tools that are used in a factory setting, that's a tough one... Factories are made up of factory workers, this can include everyone from high-level design engineers to entry-level assemblers. So, I would need to know more of the specifics.

Next, I'd like to add to the "scope of work" aspect mentioned in a previous comment. I'd make sure your manager was looped into this process as they will have their own insights, especially with concerns to priority and foundation building. It sounds like the current situation may be pretty lacking in regard to documentation control processes.

To start, I recommend finding a strategy for notetaking and sticking with it. You are likely going to be ingesting copious amounts of new information: product specifics, process breakdowns, known issues, document version control, editing hierarchy, and even more. If you can take notes effectively AND review those notes within 24-hours of creating them, you will in fact (to the shock of my grade-school self) remember the information better.

For resources... dang, where to start? Technical Writing Process by Kieran Morgan is a great place. This book gives a fantastic general overview of what goes into a technical document (process breakdowns and how-to guides). And, it offers some specific templates that you can start using immediately. There are a ton of websites and blogs (including my own) that can also point you in the right direction.

Best of luck to you and CONGRATULATIONS!

I found this book, <em>The Technical Writing Process</em> to be incredibly informative and engaging when I first started out as a technical writer. I know you mentioned a few of the common software programs, but thought maybe something a little more linear would be a good option as well. Morgan really nails the process with this text, he provides both large overviews and step-by-step best practices.

Best of luck to you.

Hey, I'm a tech writer and I write fiction! (Actually I run a small ebook publishing company too). Technical writing has helped me with the production and formatting a lot. My latest fiction endeavor is here https://www.amazon.com/Minor-Sketches-Reveries-Alberto-Balengo-ebook/dp/B089GHYB87/ (It's mostly fairy tales for adults, but there's one or two stories obliquely related to technical writing). Not trying to self-promote, but if anyone wants a free copy of the ebook, send me a private message with your email address.

Related to this is a comic novel I've been writing about the life of an unemployed writer -- won't be finished for a few years. Not really about technical writing, but some parts of it are specifically tech writing adventures.

It makes perfect sense that a technical writer would write sci fi (and obviously science nonfiction), but I never could write science fiction -- though perhaps technical writing has taught me a lot of skills about doing technical research.

Modern Technical Writing by Andrew Etter: https://www.amazon.com/Modern-Technical-Writing-Introduction-Documentation-ebook/dp/B01A2QL9SS

I write with a 55 gram resistance Topre realforce Keyboard, mainly because I type like a barbarian, and pound down the keys:

https://www.amazon.com/Realforce-87U-Tenkeyless-55g-Black/dp/B00MV84Y2Y

I would tell you why, but the Amazon reviews do a much better job. It took me a week to get used to it... But joy to me have I never looked back. I'm a touch typist, so my keys don't have any symbols on them, or rather, they are black, on black, do very difficult to see. The white might be more your speed.

The folks at r/mechanicalkeyboard can help you further. Or ask away if you have any questions. I'll be sure to answer.

Why 55g? Because I type REALLY hard, the added resistance of the key pushing back is wonderful. Although I would try some 70g pandas if you really like pressing down on the keys.

I have an external number pad that I use, I find having my keyboard directly in front of me is Bette than having it slightly off to the side with a full keyboard, that way I can have my mouse where my numberpad normally is, and my number pad where my mouse normally is. I have another tech writer friend that uses her mouse left handed for a similar reason.

What kind of graphics are you adding? At most I'll add in a screenshot of something in the UI if I need to call out a detail, but other than that I try to just rely on descriptive text. I also avoid making graphics that are essentially pictures of text, because those can't be seen by screen readers.

Any "graphic design" is handled by our UX guy and the person over in Marketing who does all the images for the main website. All I ever do is screen captures.

If you're referring to infographics, this seems to be the canonical text: The Wall Street Journal Guide to Information Graphics.

>I’m mostly using MadCap Capture

At my job we have the full MadCap suite of tools, including Capture. Within two weeks I went and bought a Snagit license with my own money. Using Capture was like going around your ass to get to your elbow, especially since I'd been using Snagit for close to a decade at that point. So you may also be hitting a limitation of the tool, depending on what kind of problems you're having.

&#x200B;

Auto spam filter caught this post because of the shortcut link. If you're suspicious of the shortened URL, the link refers to : https://www.amazon.com/Developing-Quality-Technical-Information-Handbook/dp/0133118975

I use this to teach technical and professional writing to ME undergrads.

Writing in Engineering: A Brief Guide (Short Guides to Writing in the Disciplin) https://www.amazon.com/dp/0199343551/ref=cm_sw_r_cp_api_i_Xci-AbSM0WRE9

It’s short, to the point, and fairly affordable compared to textbooks.

I taught remedial writing a couple years ago as a grad student and tutored writing for years before that. I think it's important to figure out what your coworker's daughter needs to improve. The Elements of Style is a style manual. It's prescriptive for that very reason. Imo, it's not a great resource for developing writers, but it's good for formal essays/reports because it can help a student create consistent style without being as comprehensive as say The Chicago Manual of Style.

Some of my favorite resources for developing writers are Eats, Shoots & Leaves and Woe is I. These are less grammar books and more books about grammar, if you get my meaning. They're fun, easy reading meant to develop an understanding of writing rather than embed the (current) conventions.

Also, I've worked with enough students to know that if writing is already a challenge, a book is probably not going to be helpful. She needs to find what works for her. It's pretty unnatural to write in isolation, but that's often what schools and teachers demand.

Yes. The 4th edition (2016) changed the name to Garner's Dictionary of Modern English Usage. To reflect the broader nature of the work compared with previous editions.

Garner's Modern English Usage https://www.amazon.com/dp/0190491485/ref=cm_sw_r_cp_apa_VegWzbFS5R2VB

It's not free, but &quot;Eats, Shoots &amp; Leaves&quot; by Lynne Truss is a pretty great read about the importance of punctuation. AND it's cleverly written.

Aside from the fact that the whole sentence can be removed in this instance - no, the comma isn't exactly necessary here. I hate commas in general. Sometimes they are necessary, sometimes they are just for adding pause for the reader to take a breath.
&nbsp;
This is one of my favorite books and has been extraordinarily helpful whenever I start questioning myself. This is just the part about commas but it might help. :)
&nbsp;
Comma Sense by Richard Lederer

If you need a course to pad your CV, then find whatever course is cheapest and quickest. Online courses are a waste of time and money.

Tech writing is easy. Small words. Small sentences. Active voice. Write with nouns and verbs.

Just like good engineering: remove all the parts you don't need.

If you want to be able to "talk the talk", read up on XML (which is simple if you know any HTML), DITA, XSLT.

I assume IBM has a style manual for tech writing. Get a copy of it and learn it, know it, live it.

My favorite style guide is http://www.amazon.com/Technical-Writing-Structure-Standards-Style/dp/0070061734

Written 40 years ago, it is still better than any other tech style guide I've read. Short and sweet. Very similar to Elements of Style (Strunk & White).