Planet Open Help

The life and work of the open help community
Join our planet

July 14, 2017

Lana Brindley Lana Brindley

Writes too much, reads too much, talks too much, thinks too much, drinks too much. Generally superlative.

OMG, my ACL! Pre-surgery update

In the last month, with the aid of lots of physio (and, more recently, hydrotherapy) I’ve managed to get my knee to the level of movement that my surgeon wants (130°! Whee!), I’m getting around without using the brace or my cane at all, and so I’m all booked in to have the surgery on Monday. So this week has been all about preparations. Here’s what I’ve organised:

    Some assistance at home for the next week. In other words, Mum’s coming to visit! (Note that I’ll be setting up the couch for her before I go into surgery, because there’s no way I’ll be doing it after)
    Freezer meals. I’ve got about a week’s worth of cooked meals in the freezer, ready to be reheated.
    Groceries and general stocking up. While home delivery is great (and I’m sure I’ll use it), I don’t want to be running out of toilet paper in the first few days!
    A breakfast tray so I can easily eat, or use my laptop in bed, or on the sun lounger on the deck. I’ve also moved a laptop charger next to my bed.
    And it might seem weird, but just general tidying up. Making sure there’s nothing to trip on, for starters, but also because I don’t want to be staring at the filthy floor in a week, wishing I’d vacuumed.

Other than that, it’s all the medical things. I’ve fielded at least three calls just today from various specialists and the hospital, checking on medications, time to arrive, and general information about the surgery. I’ll confess, I’m a little nervous, but I’ll be so glad to have this done and finally be on the road to recovery!

by Loquacity on July 14, 2017 01:49 AM

June 10, 2017

Anne Gentle Anne Gentle

Author of Conversation and Community: the Social Web for Documentation. I’m a writing fiend, technical geek, community doc nut, + Content Stacker for OpenStack.

How Lucas Systems Integrated Swagger OpenAPI Definitions with API Explanations

Now available on docslikecode.com, this explanation of how to integrate Swagger with Swashbuckle for a REST API written with C#.

A Pirate’s Life for Me: Documenting APIs with Swagger

In it, Adam Locke, their lone tech writer, describes his troubleshooting process, the toolset including DapperDocs, OpenAPI, Nuget, Packet, and some clever code.

I appreciate reading about both the stop-and-start struggles and the clear wins found in this case study. Plus, it provides insights into how REST APIs can be written in any programming language. I have found it’s best to lean into the language your coworkers know best. Then you can get the collaboration gains offered by integrating the docs and code as tightly as possible.

by annegentle on June 10, 2017 01:34 PM

June 07, 2017

Lana Brindley Lana Brindley

Writes too much, reads too much, talks too much, thinks too much, drinks too much. Generally superlative.

OMG, my ACL! One month update

Some good news, I’m getting around without any walking aides (although I keep my cane close by, I’ve started referring to it as my ‘moral support’ because I really don’t need it any more). While I’m at home I’m also walking around without my brace on, too, trying to strengthen muscles in my leg and knee. With help from my wonderful physio Greg, I’ve got movement between about 2° and 100°. The visible swelling has more or less completely gone, although it’s still swollen inside, which is why it’s still so hard (and painful!) to bend and straighten it.

But, my surgeon wants more! So, surgery has been put off for now, and the physio continues until I can get to around 130°. Dr. Davies tells me this is will greatly help my recovery, and will mitigate the risk of the joint freezing after surgery (which would require more surgery, and I’d rather not do that!). So life is more or less back to normal, although I’m still being quite careful about where and how far I walk, I can get around pretty easily again now, which is a great relief!

Read on …

by Loquacity on June 07, 2017 01:11 AM

June 06, 2017

Anne Gentle Anne Gentle

Author of Conversation and Community: the Social Web for Documentation. I’m a writing fiend, technical geek, community doc nut, + Content Stacker for OpenStack.

Versions for docs sites with Jekyll

Versions of software product or a service need documentation sites to match those version numbers. As I investigated and learned more, I found layers of complexity when using a source control system to version the source documents while outputting a nice user experience with a static site generator such as Jekyll.

I have one possible solution to try out in this repo: https://github.com/justwriteclick/versions-jekyll/. Give it a try!

by annegentle on June 06, 2017 01:28 PM

May 29, 2017

Anne Gentle Anne Gentle

Author of Conversation and Community: the Social Web for Documentation. I’m a writing fiend, technical geek, community doc nut, + Content Stacker for OpenStack.

Git and GitHub for Technical Documentation: Reviews

Writers might hesitate to work with others on content deliverables, and developers might feel they have little to contribute to the documentation. I assert is that no one can know everything, so distribute the workload by writing together just like you collaborate together on code.

What about reviews? How do you maintain quality while working on documentation in a code repository? Here are a couple of ideas.

If you have an active reviewer pool, one tip that sounds like an anti-pattern is to have your most active reviewers wait. Even if it’s only for a few hours, let the less experienced reviewers review first. Then have your more experienced reviewers review second. The less experienced reviewers learn if they missed some small detail or need to learn to step back to a wider context. These judgement lessons are difficult to teach without examples, so I suggest a wait.

Another tip that I really like but haven’t yet put into practice formally is to use a checklist. You could start with a fairly simple review checklist, such as:

  • Does the document build without errors? Automated testing sure helps with this checkbox!
  • Does the information belong where it is placed?
  • Does the change match the shared style guide?
  • Are the agreed-upon names and terms used correctly?
  • Do all the commands in the change work correctly? Here’s where automated testing also helps.
  • Does the commit message convey the purpose of the change?
  • Does the change claim to fix a doc bug, and if so, have you read the bug and agree with the proposed fix?

Sign up for a series of lessons on treating docs like code, and get a free PDF file of a review checklist for doc changes when using Git, GitHub, BitBucket, or GitLab, or any other source code system for your documentation.

by annegentle on May 29, 2017 05:53 PM

Lana Brindley Lana Brindley

Writes too much, reads too much, talks too much, thinks too much, drinks too much. Generally superlative.

Gemdale Travel Money Laundering Job Scam

Came home to an interesting email on Friday:

My first thought was that Seek shouldn’t be passing my details on to anyone, but as I dug further it got more and more interesting. Here’s the job description:

I don’t know about you, but “process payments between our clients and our company” sounds an awful lot like money laundering to me. No reputable company needs to transfer money through some random person’s bank account.

This is a slick operation, and it was pretty clear to me that this “Gemdale Travel” was operating outside of Seek’s terms of service, so I called Seek to let them know. The customer service operator was brilliant, and explained that Gemdale have been dogging them for some time. They obviously have no connection to the legitimate business Seek undertakes, and this is a sophisticated scam. Gemdale appear on the surface to be quite legitimate, until you scratch.

Most job scams tend to be of a more simple sort, where they extort money out of victims for expenses, but a job never materialises. This is another level, not so much a job scam, as a pure and simple method to find people to launder money for them. The victim could potentially sign up for this gig, do the job, and never know that they’ve been complicit in a crime until the police show up.

Be careful out there, lovelies.

by Loquacity on May 29, 2017 12:33 AM

May 21, 2017

Lana Brindley Lana Brindley

Writes too much, reads too much, talks too much, thinks too much, drinks too much. Generally superlative.

OMG, my ACL! Second week

I saw my GP again on Tuesday morning (12 days after the injury), and we decided that going to a private surgeon at this point would be a good idea. Waiting times for ACL surgery through the public system can apparently be six months or more, and I was eager to get back on my feet. By this point, I could fully weight bear on my bad leg, and had ditched the crutches for my trusty cane (which I bought years ago when I hurt my calf muscle, and was quite pleased to be able to put back into service). My knee was still swollen, although it was going down ever so slowly, and I still had zero stability in the knee, although that’s not terribly surprising.

I was referred through to QCOS at the Wesley, and I secured an appointment with Dr. Davies on Thursday (14 days after injury). By the time I saw Dr Davies, I was hobbling quite effectively on my peg leg (remember, my brace was still locked straight at this point), and could do a few steps in a straight line without relying on my cane.

The first thing Dr. Davies did was look at my MRI and explain the injury to me. He showed me where the meniscus was torn, and where my ACL wasn’t. For my part, I did my best not to throw up on his desk. He then examined my knee, pushing and poking to work out how much give there was in the joint (spoiler: too much), and asked me to bend my leg as far as possible. At that point, I could get to a very uncomfortable 50° or so. It’s hard to describe the feeling, but it’s almost dry, like there’s no lubrication in my knee, and there’s a lot of pressure on the joint when I bend it.

Dr. Davies then unlocked my brace to 60°, prescribed me to see my physio twice a week, and booked me in for surgery for 19 June. I had four weeks to build my leg muscles back up, and get full range of motion. This, I will note at this point, was in direct contravention of what the physios at the hospital told me. Dr. Davies was polite about them, but I won’t be. They gave me bad advice, and set my recovery back by at least a week by telling me not to move my leg, or to keep working on range of motion. Additionally, locking your knee straight puts pressure on the ligaments that are trying to heal (they are at rest at around 30°), so it’s counter productive. If you get told this, seek an opinion from another physio.

So at this point, two weeks after the injury, I finally had a plan for getting on my feet again! Four weeks until surgery, six weeks rehab afterwards, nine to twelve months before I was fully back to normal. It seemed like forever.

Read on …

by Loquacity on May 21, 2017 02:18 AM

OMG, my ACL! The first week

I sat around and felt miserable for a couple of days over the weekend, then went to the GP on Monday, and got the MRI done on the Tuesday (four days after the injury). This was my first MRI ever, and I have to admit I was not prepared for the clunking and beeping that machine makes. All the noises sounded, to me anyway, like alarms going off, and I kept on expecting someone to come charging in and pull me out because the machine was malfunctioning. Needless to say, they didn’t, and that’s normal operating procedure. Who knew?

My GP called me with results on Thursday evening. It was not good news: a torn ACL, sprained just about everything else, and a torn meniscus. Surgery was looking to be a distinct possibility. At this point, I could partially weight bear on the bad leg, probably around 50%. I’d been taking Panadol (paracetamol) for a few days, and still was before bed to help me get to sleep, but otherwise wasn’t in much pain at all. My knee was still very swollen, though, and I really needed to wear the splint 24/7, without it my leg felt … well … *floppy*.

Friday was my followup appointment at the hospital (eight days after the injury). Sadly, I didn’t get to see the same physio, instead I saw two others, who surprised me by telling me that I didn’t need to see a physio before the surgery, and sent me down to get a new brace, but that it would be fixed in a straight position until after surgery. This contradicted what I’d read online, but I trusted them, since they were the professionals (and since I have a healthy skepticism of anything I read online). They gave me a referral to a surgeon, and once I had my fancy new exoskeleton brace, I was on my way again.

Read on …

by Loquacity on May 21, 2017 01:56 AM

OMG, my ACL! The day of the injury

So the story begins early on a Thursday morning, at a boxing class run by my trainer, B. I was doing a set of split box jumps on a fitness step with three risers (like these ones). On the seventh rep, my left foot landed on the ground, and presumably twisted, my knee went pop, and I went down with a yell. Interestingly, there was no immediate swelling or bruising, but I was in excruciating pain, so I think from the perspective of everyone else it probably looked like I was complaining about not much. Well, I showed them! They got me lying down with a rolled towel under my bad knee and an ice pack after I started going into shock, while an ambulance was called. When the ambos arrived, they gave me a green whistle (Methoxyflurane. Incidentally, I learned that this is an Australian invention We’re a smart bunch here in Aus, aren’t we?!) which pretty much took care of the pain, and had the upside of making me fairly entertaining on the way to the hospital.

When we got to hospital (RBWH) I was seen pretty quickly by a doctor and a physio, and had an xray to rule out a fracture. The standard way, I’ve learned, to diagnose an ACL tear is to grab the lower leg and push against the knee to see how much sideways movement there is (if this is making you cringe just thinking about it, then you can probably guess how I felt about it at the time). The physio tried this with me but I tensed up so much (“guarding” was the term he used in his report) that he was unable to diagnose me at the time. Eventually, he said he thought I’d probably done my ACL but he couldn’t tell, gave me a knee splint and some crutches, a referral to my GP for an MRI, and a followup appointment for a week’s time.

Read on …

by Loquacity on May 21, 2017 01:44 AM

So that happened …

As many regular readers will know, I’m a bit of a gym junkie. And if you’ve ever tried to book a meeting with me early on a Thursday morning, you’ll know that that is when I do Boxing. Every week, without fail. And so it was a couple of weeks ago. Towards the end of a 45 minute session, I was most of the way through a set of split box jumps, when my knee went pop, and I fell to the ground. To cut a long story short, I ended up with a completely torn ACL, minor sprain of the PCL and ACL, and a meniscus tear. Basically, I did a good job (in blog posts like this, I’ve learned, here is where they often put a gory picture of the inside of a knee, which I’ve taken to quickly scrolling past, so I’ll leave googling for that image as an exercise for the reader).

Normally I don’t write about this kind of thing, but as I’ve been laid up I’ve been doing a bit of googling about knee injuries and the surgery that goes with them. It’s a very common sports/gym injury, and there’s lots of info there, but not a lot from an Australian perspective, so I thought I’d spend some time chronicling my experiences, and hopefully it’ll help someone out.

Day 1
The first week
The second week
One month update

by Loquacity on May 21, 2017 01:08 AM

Subscriptions

  • Anne GentleAnne Gentle Author of Conversation and Community: the Social Web for Documentation. I’m a writing fiend, technical geek, community doc nut, + Content Stacker for OpenStack.
  • Jim CampbellJim Campbell HRIS admin to the stars, and documentation writer for needy open-source projects. As a Chicagoan, I also know enough to not put ketchup on a hot dog.
  • Lana BrindleyLana Brindley Writes too much, reads too much, talks too much, thinks too much, drinks too much. Generally superlative.
  • Shaun McCanceShaun McCance GNOME documentation team lead. Programmer. Technical writer. XML expert. Community leader. Free software enthusiast.