Author Archives: Sarah Maddox

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!

API Technical Writing – tcworld India 2016

This week I attended tcworld India 2016 in Bangalore. What an amazing experience! I’ll write a summary of the conference soon. First, here are some notes on a session that I presented at the conference: “Introduction to API Technical Writing”.

The slides for my presentation are available on SlideShare: Introduction to API Technical Writing (slides).

Presentation overview:

  • An introduction to APIs.
  • An overview of the role of API technical writer, and of our audience – the developers who need our documentation to use
  • APIs in their applications.
  • A technical writer’s view of the types of API we might document.
  • Demos of 2 APIs that you can play with yourself.
  • The components of API documentation.
  • Examples of good and popular API documentation.
  • Working with engineers.
  • Tips on getting started as an API technical writer.
  • Why API technical writing is a good field to be in.

API Technical WritingThank you so much to everyone who attended the talk. The room was packed to overflowing. After the session, and indeed throughout the conference, people came up to discuss the field of API technical writing and to show me things they were working on. A number of conference attendees do API documentation as part of their role, and it was very interesting to see the variety of requirements even in this niche within a niche: API documentation within the technical writing profession.

For the next tworld India, I think it’d be a good idea to have a panel discussion on API documentation. We could invite 3 or 4 people working on different types of APIs, and within different environments (such as internal versus external documentation, or integrations).

Follow

Get every new post delivered to your Inbox.

Join 1,716 other followers

%d bloggers like this: