Category Archives: technical writing

Set size of browser inner window for screenshots in Chrome

I need to set the size of my browser’s inner window, so that I can take screenshots that fit into a specific area and have consistent dimensions. After doing a bit of searching and experimenting, I found that you can do it nicely with Chrome Developer Tools. This is handy, because Developer Tools are a standard part of the browser. There’s no need for any add-ons.

Here’s how to set the dimensions of the inner window (viewport) in Chrome.

In short

  1. Open Chrome Developer Tools.
  2. Click the Toggle Device Mode option near top left of the developer tools section.
  3. Choose Responsive from the dropdown menu at the top of the screen.
  4. Edit the dimensions, which are also at the top of screen, right next to the dropdown.

The longer version

The screenshots show Chrome version 49.0.2623.110 m.

1. Open Chrome Developer Tools.

Press Option+Command+J on a Mac, or Ctrl+Shift+J on Windows, or open Chrome’s hamburger menu and choose More Tools > Developer Tools:

Chrome Developer Tools

The Chrome Developer Tools panel opens in your browser. By default, it opens either at the right-hand side or at the bottom of your browser window. It can also open as an independent window. I have mine set to open at the bottom.

2. Click the Toggle Device Mode option near top left of the developer tools section.

The icon for Toggle Device Mode looks like a mobile device snuggling up to a larger screen.

Chrome Developer Tools

3. Choose Responsive from the dropdown menu at the top of the screen.

When you’re in “toggle device” mode, a dropdown menu and editable screen dimensions appear at the top of the window. Make sure the dropdown menu is set to Responsive.

Chrome Developer Tools

4. Edit the dimensions, which are also at the top of screen.

The dimensions are editable when the dropdown is set to “Responsive.” You can also set the relative size (100% in the screenshot).

Chrome Developer Tools

That’s it. Happy screenshotting!

Where does Screeny put the recorded video or image file?

I’ve been experimenting with Screeny by Daeo Corp. Software, for recording screencasts on a Mac. It works well, but it took me ages to figure out where the app saves the movie or image files.

Here’s the answer: Screeny creates a “Screeny” directory inside your “Movies” directory, and puts the files there. They’re .mov files.

~/Movies/Screeny

​Here’s an example file name:

Screeny Video 26 Mar 2016, 5.47.45 AM.mov

​Here’s what the directory looks like in Finder:

Where Screeny puts its movie files

Screeny puts the files in that directory as soon as you stop recording. There’s no way to change the default location of the files.

​What about single screenshots? Screeny puts those into a Screeny directory in your “Pictures” directory:

~/Pictures/Screeny​

​Example file name:

Screeny Shot 26 Mar 2016, 6.09.59 AM.png​

I hope this helps you find your screencasts.:)

Playing with Corilla, a new tech writing tool

David Ryan and team have just announced the first beta launch of Corilla, a collaborative publishing tool for technical writers. Huge congrats! This is a big milestone for a new product. The Corilla team are inviting us to try out the beta release and give them feedback, as a way of helping build a great product for tech writers. So, here goes. I’ve had a lot of fun playing with Corilla, building my first doc set.

I created a Corilla collection, which is a set of topics for publication. I didn’t have any real idea of what I’d write about. I just clicked get started today on the launch announcement and took it from there. It’s a smooth getting started experience. My only question was the significance of the team name during registration. I entered a team name of “DocsFTW”, on the premise that nothing can go wrong with a name like that.:)

My first cruise with Corilla

After registration, the welcome screen has a nice greeting and useful information on how to get started:

Corilla for technical writers

Next I clicked through to Topics, then New Topic, and got this dialog:

,Corilla for technical writers

Nice: Context-sensitive help appears in the form of popups on the right-hand side of page when you open a section of the app for the first time (not visible on my screenshot). You can also click the help icon at bottom right at any time.

There’s more context-sensitive help within the UI itself, as you can see in the above screenshot. The wording needs a bit of tech writer love: It should probably say “for example” or “e.g.” rather than “i.e.” and the language in the suggested topic title isn’t quite right.

Something cool happened when I positioned my cursor in the Title text box. Corilla suggested two titles: “Working with an engineering team”, and “The future *is* technical communication”. These are two presentations I’ve worked on recently (both as Google Docs presentations). It’d be interesting to know how Corilla got those names.

Corilla for technical writers

So, thanks to Corilla for giving me a good idea of what to write about! I decided to copy some content from my presentation, “Working with an engineering team”, into the Corilla editor.

The Corilla editor uses Markdown, which is a lovely restful format for those of us who use it regularly. If you haven’t used Markdown before, now’s your chance. It’s a trimmed down markup format, great for simple online doc output and easy to read in its raw form.

Corilla for technical writers

After creating a few topics, the next step was to add some of my topics to a collection, which is the unit that Corilla makes available for publication. There’s a nice drag-and-drop feature for adding topics (on the left) to a collection (on the right):

Screen Shot 2016-03-12 at 6.11.10 AM

Here’s the published result, which you can see online at the Corilla viewer: Working with an Engineering Team. The following screenshot shows part of the page:

Corilla for technical writers

It’d be nice to have the topic titles more prominent in the HTML output, with an indication of where the title fits into the page. Currently the output appears as one long page, including all topics. The topic titles are on the left, but it’s not clear which bit of text they belong to. The only indication of a topic break is a horizontal line, such as the one above “Teamwork is key…” in the above screenshot.

You may notice that my published output has some weird characters every now and then. For example, instead of “It’s” you’ll see this:

It’s

That’s because I copied my content from a rich text editor into the Markdown editor. I wonder if there’s some way Corilla can detect and correct such nuisances?

One more suggestion for the Corilla team:  A user profile is identified by an email address, and the email address appears at the top right of every page. It’d be nice to have a name instead, both to make the experience more personal and to hide the email address. (I’ve adjusted mine in all the screenshots on this page.)

Congrats Corilla team!

Congrats to the team on the beta launch! The launch blog post describes upcoming features:

  • In-line contextual formatting
  • Views for version control diffs and merges
  • Bulk importing/exporting
  • Multiple format outputs (ePub, PDF, other APIs, etc)
  • Media and file management
  • Slack integrations (among others)
  • Improved onboarding and documentation
  • Editorial and QE modes
  • Published content analytics
  • Improved multi-author mode
  • Customisable CSS on published collections

I’m looking forward to seeing more on the collaborative editing and version control side of the product. And content analytics will be very cool too. I hope the team gets lots of good feedback from the technical writing community!

Webinar on API technical writing with STC India

Are you interested in learning about APIs and API technical writing? Join us for a webinar, hosted by STC India. I’ll demo a couple of APIs and discuss the role of a technical writer in this area of the software industry. We’ll look at examples of API documentation, and discuss what type of documents an app developer expects when using an API.

The title of the webinar is “Introduction to API Technical Writing”. It’s intended for technical writers who know little about APIs (application programming interfaces) and want to explore the field of API technical writing. My hope is that, after attending this webinar, you’ll have the knowledge and tools you need to head off on your own explorations.

APIs (application programming interfaces) make it possible for applications to share information with each other. You could say that APIs are the communication channel of the online world. Developers need help hooking their application up to someone else’s APIs. We, as technical writers, give them that help.

Recording of the webinar [Update on 10 April 2016]: The recording of the webinar is now available on YouTube: Introduction to API Technical Writing.

Registration details: Sign up for the webinar, and read more about it on the STC India site.

Date and time: Friday 18 March 2016, at 1pm Indian time – that’s 6.30pm in Sydney. The session lasts one hour.

Who can join? Anyone. It’s free of charge, and you don’t need to be a member of the STC.

Topic overview:

  • An introduction to APIs.
  • An overview of the role of API technical writer.
  • Our audience – the developers who need our documentation to use APIs in their applications.
  • The types of API we might be asked to document.
  • Demos of 2 APIs that you can play with yourself.
  • What API documentation consists of.
  • Examples of good and popular API documentation.
  • Working with engineers.
  • Tips on getting started as an API technical writer.

Hope to “see” you at the webinar.:)

tcworld India 2016 wrapup

This week I attended tcworld India 2016 in Bangalore. It’s been an amazing, rewarding experience. Here are some of my impressions, and a roundup of the posts I’ve written about the sessions I attended.

Tcworld India is an annual conference run by TWIN (Technical Writers of India) and tekom Deutschland. This is a great event, attended by 350 energetic, knowledgable technical communicators.

In his introductory speech at the start of the conference, Akash Dubey said that the great thing about tcworld India is the learning that happens in the corridors. That is so true! At every step, I met people with things to discuss, things to show, questions to ask, answers to propose.

The stage before the start of the conference, awaiting words of tech comm wisdom:

tcworld India 2016

The sessions

There were 8 time slots on each of the two days of the conference, with up to 4 sessions running in each time slot. In total that makes approximately 30 sessions, covering topics across a range of areas: content strategy, tools, technologies, trends, usability, authoring and editing, structured writing, career development, leadership, localisation and translation, and more.

The following posts contain my notes about the sessions I attended:

Bangalore

The conference took place in Bangalore, India. My travelling bookmark has some impressions of the city to share: Bangalore peace and traffic.

Thanks

Thank you to the organisers of tcworld India 2016, for a very well planned event and a skilfully constructed program. The care that you put into this conference is obvious. Walking around the halls, I saw happy, busy, engaged attendees and packed sessions throughout.

The party!

Technical communicators in Bangalore sure do know how to throw a good party. The venue was beautifully decorated:

tcworld India 2016

We started with a few song and dance numbers from some very talented technical writers. I filmed some short videos, which capture the spirit and beauty of the event:

Another dancing item:

There was so much more. Guitars:

tcworld India 2016

A sax:

tcworld India 2016

Singers:

tcworld India 2016

A huge thank you to the performers who put so much effort and talent into the show. I was blown away by the beauty of it, and so were all the attendees. Talented technical writers indeed!

After the show, the rest of the crowd got into the dancing scene:

tcworld India 2016

Thanks again, tcworld India 2016!

Follow

Get every new post delivered to your Inbox.

Join 1,690 other followers

%d bloggers like this: