Latest update in the docs consolidation project: a page that has only 1 section/example in some of our less complete docs sets is up to 5 sections/24 subsections in the consolidated page.
The page is now so long and comprehensive that you have to scroll the “On This Page” table of contents in the sidebar.
We’ve decided that’s too long and will split it into a few pages. But this project is already yielding great results by increasing the comprehensiveness of our docs.
#TechnicalWriting folks of Mastodon!! At my New Job I have to select a tool for redoing and managing our docs in a structured way. These include manuals and datasheets (Web and PDF), and contextual help, so content reuse is important.
I'm completely in over my head as the only writer. I've never managed doc projects nor used specialized documentation tools, having worked mostly in HTML/MD formats and Word files for customers, so have not been involved in publishing them.
@tiikerikani I'm using Paligo at work and I'm extremely impressed. I manage around 700 pages of various content, exported to HTML and PDF, and it works great.
Paligo is also big on content reuse, and it's really easy. I can also vouch for their support team, which is great.
I previously worked in Author-It and it waa horrible. But I will always recommend Paligo.
🧵 I have lots of respect for the developers of Textual, so this is friendly, constructive criticism
I feel like the UX of this app could be greatly improved by incorporating some #technicalwriting practices, as well as some things I have learned working in tech for the last few years
First off, when you try to connect to a server and mess the URL up somehow, it gives no feedback on what it doesn't like about your input. So I have no idea what I need to fix
And last, this confirmation dialog suffers from a similar problem as the starting screen and the text validation error. "Do you want to delete the selection?" is, again, too general. It doesn't say which server will be deleted, which is confusing
I think these types of dialogs are handled pretty well in Cork (2nd pic) by including the name of the item in question in the alert
In today's fun with API docs, I started a new project using GitHub's GraphQL API. Again.
This time I'm mucking with Issues. Issues have participants. Participants is a UserConnection! - fine, a bunch of other fields have this type so I know it.
But the definition is:
"A list of Users that are participating in the Issue conversation.”
So... what does “participating" mean? People who leave comments? What about reactions, do they count? Is the issue author a participant?
Is it legitimate to write in a #manual for a piece of equipment (that improper use of could lead to damage, injury or death):
If you find yourself asking 'should I be doing this?' the answer will always be 'No'.
?
Seriously I'm running out of ways to say:
don't sit on it, swing from it, stand under it, hold onto it, put your genitals in it, lick it, fart around it, taunt it, make it watch Hayao Miyazaki movies (although it would like them), or feed it pie after dark.
Undocumented killer feature:
Weirdly incomplete Boeing 737 MAX manuals
Inspired by recent news about a decompression incident, I wrote about missing information in airplane manuals and their consequences. This post owes a lot to two discussions on Mastodon, which I've cited in the post.
I just received the news that I passed the CPE exam that I took last month! Now I’m a certified English language expert. There is literally no higher-level exam than this one.
I returned to work today and discovered that Renee, one of the speakers at the Australian #wtd2023 conference, has blogged about the conference with a kind paragraph or two about my talk.
SO got us a cool reflector telescope. I've only ever used kid-targeted refractors before so it's an adventure.
I'm gonna gripe that if your "beginners guide" uses the terms "Dec, or collimation" or any of a dozen other telescope specific terms without defining them, it's not a beginners guide!
The quick installation guide said things like "Attach to Dec screw" with no picture or further explanation. Gah!
This will always mean fewer success cases, poorer views of your product within your ecosystem, more unhappy developers or users, and a negative impact on your brand or company.
Docs are a serious sub-product in their own right, are an investment, and must be part of your wider product strategy."
Everyone is looking to me for API doc best practices and process. Validating, but also a little intimidating, like the teacher learning the content the night before to stay ahead of the API doc class while teaching seven other classes at the same time.
I'd appreciate y'all sharing any thoughts & references & resources, from theory to implementation.
@rekiwi At govt.nz we used Swagger (https://swagger.io/) to document our APIs, and I thought it would provide a good basis for teaching how APIs work and even developing or extending an API.
I’m baffled that these companies out there are still demanding that you complete their „writing ability assessment test“ when you have 10 YoE in the field, a large portfolio, and multiple pieces of documentation you worked on publicly available.
What’s even the point of my portfolio if I still have to do these assessments during every single interview process!
I get it, it's great if you're just starting out, but not when you've been working as a Senior for multiple years.
@davidbures My spouse has the same issue with coding assessments as a principal dev with 20+ years of exp. They have started asking interviewers if they can “test out” by pointing to a specific example in their portfolio depending on what the interviewer is looking for. The next time I’m interviewing, I will definitely do this.
The other day, I was talking with the head architect for our company’s software. I was complaining about how little I’m paid as the lead tech writer for four of our products.
He told me to transfer to his department as a programmer, and that I’d be making more as a junior developer than I do as a lead tech writer.
I don’t know what that says about the state of the software industry...
I wish the industry distributed salaries more fairly! I hear C-levels talk about “the cost of talent.” I think a writer who can also code is pretty rare and should cost as much as a developer - or more, even! They are very distinct skills. So “cost of talent” doesn’t hold up. It’s about how much organizations value technical writing, and the answer is never enough.
@dachary It’s great to know I’m not alone! I suppose they would pay more for a “developer who can write” than a “writer who can develop.” Honestly, I think it should be the opposite. I can understand what the users want while also knowing how to implement it, which is not something a “developer who can write” can do! They’re always developers first.
Last week, I posted about how I used our fall hackathon to get Google Analytics data out of a spreadsheet and into MongoDB Atlas.
This week, I'm looking at how I transformed documentation metadata in Atlas to make it easy for us to get the insights we want. I look at what questions we want to ask, and what data we need to support those questions. And then dive into some practical aggregation pipelines to set up the data.
After a weekend digging post holes in hard clay, I really appreciate sitting and typing.
In fact most everything I've done for pay, from singeing the hair off my forearms with a wok burner to laying on my back in muddy ice-water hooking up rental trailers, makes me really appreciate sitting and typing.
@voxpelli@snarfed.org@snarfed.org Thank you! I definitely need help to enable comments to appear on my wordpress.com blog. While it worked before in my other blog, it doesn't seem to work now. Huh!
Hmm this could be a potentially useful guide for brid.gy. Whatever it is, maybe I need to flex my #TechnicalWriting skills by writing a dumb-as-a-rock guide for wordpress.com users, because that's what they need. I find tonnes of guides for static websites and WP.org, but not many for wp.com. The users for the latter are really not coders, so a guide would be very important.
@liztai while there aren’t a lot of guides for WP.com, part of the reason is that by the time you’ve paid for an account capable of having plugins/extensions you can probably pay someone to do the work.
Dev: behold! I added the Inverse Calibration button.
Me: great. Now I have to describe what calibration is, what inverse calibration is, and if its not readily apparent, what the difference between the two is and when you'd want to use either in liu of one another. Oh and because we have a REST API up in this bitch, I have to document /InverseCalibration and all the new JSON because you didn't reuse the same DTO as /Calibration for some (why!?) stupid reason. >:(
