Welcome to Triona Carey
Burrrr it’s cold. Just as I was going to bed last night I looked out the window to see the snow falling. We didn’t get a lot, but there are a few patches where it settled.
I can’t remember the last time it snowed in November.
This week we had a new starter at Skype who is a technical documentation writer and has been hired to write and manage the API documentation, so please welcome Triona Carey to the team.
Triona has a mammoth job ahead of her, I tired working on the docs but it blew my brains trying to separate the API into Linux, Windows and Mac, and have source code in different languages. Triona has many years experience building documentation so I am sure we can figure something out between us.
My home office is being to look like a bit of a warehouse store room, and its starting to get noticed by “she that must be obeyed”. So we need to have a bit of a competition to get rid of some of this stuff.
So have think about what you want from the API documentation and post your thoughts below, I’ll pull a winner at random and send them a prize.
In the run up to Christmas I will have lots of things to give away, so make sure you check back often to see what you need to do to win!
Remember – you have to be in to win.
Hi Lester, perhaps the most obvious but in my opinion the most critical aspect to any good API documentation is short examples for each section being described. Being able to refer to how the instruction is used along with it’s syntax is one of the easiest aspects of using Microsoft’s developer guides.
Having many platforms and the possibilities of multiple languages to choose from obviously makes this a mountain of a task but perhaps the main languages can be catered for and examples built by contributions from the developer community. Perhaps this later aspect could be run on a ‘points’ system where users could post a question and the community could offer solutions with the most appropriate being allocated points for their answer. These points could be purchased originally by the questioner, contributed by Skype or a mixture of both. Maybe run along similar lines to Expert-Exchange.com
Triona here – hi all, looking forward to getting to know you and to hearing what you need and want from our docs. Ideally we’d work from the must haves to the like to haves down through to the wouldn’t it be great. With your input and help it will be great because Skype is. Thanks in advance for your ideas.
I think you should at least include the following information in the documentation (I’ve framed it as I would have it layed out):
Introduction
What is Skype
What is Skype API
How to report a bug
Revision History
Skype API
Windows specific details (SendMessage(), COM Wrapper, etc…)
Mac OS X specific details (provided wrapper, etc…)
Linux specific details (DBus, etc…)
API Commands
Command X
Syntax
Usage
Common mistakes
Compatibility issues (older versions, cross-platform, etc…)
Example
Command Y
…
Known Issues
Cheers Michael I have been in contact with you via Skype to send you something.
Lester