Re: ASObjCExtras.framework documentation
Re: ASObjCExtras.framework documentation
- Subject: Re: ASObjCExtras.framework documentation
- From: 2551 <email@hidden>
- Date: Wed, 14 Jan 2015 17:13:58 +0700
> On 14 Jan 2015, at 09:46, Shane Stanley <email@hidden> wrote:
>
> (The irony of it falling to a non-native-English-speaker to make things clearer is not lost on me. What can I say?)
A couple of years ago I did a postgrad degree in technical document writing, and got pretty involved with both the ISTC (http://www.istc.org.uk )and the main tech writers mailing list (http://www.techwr-l.com). In those circles, developers are renowned (and regularly castigated for)
i. not writing documentation at all
ii. not keeping documentation up to date
iii. writing documentation that, from a user's perspective, is utterly obtuse and practically useless
As I've left tech writing more-or-less aside and turned into a would-be developer myself in the last couple of years, I find myself committing sins i. and ii (though I hope not iii, but I'm not the one to judge).
It's easily done, for three reasons.
1. When your creative energies are exhausted in producing good code, there's little left over for producing good, clear user-friendly documentation.
2. On top of that, it's generally the case that the all-knowing developer is not best-placed to put themselves in the shoes of the know-nothing user and second-guess what and how the documentation can best help that user. Tech writing folklore is replete with examples of developer-written documentation that utterly fails to address the real needs of the user.
3. Tech writing is a skill, and it's not even remotely connected to the skills needed to be a good developer/coder. Some people may have both, but there's no reason to expect that just because you wrote the code, you're the best person to explain how to use it.
Short Story: don't beat yourself up about it.
Short Story II: if you're not lucky enough like Shane to find a volunteer, hire a professional.
Best
Phil
DisplayDroid beta (a lightweight script editor and automation tool) is now available for free download. More info on sqwarq.com/displaydroid
http://applehelpwriter.com
http://sqwarq.com - apps for OS X & iOS
_______________________________________________
Do not post admin requests to the list. They will be ignored.
AppleScript-Users mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
Archives: http://lists.apple.com/archives/applescript-users
This email sent to email@hidden