tag:blogger.com,1999:blog-19727408.post7877517261408995150..comments2016-07-20T09:43:51.417-04:00Comments on X-Plane Scenery Blog: Documentation Is Not Like CodeBenjamin Supnikhttp://www.blogger.com/profile/04886313844644521178noreply@blogger.comBlogger7125tag:blogger.com,1999:blog-19727408.post-69037628733373603422009-12-30T19:22:25.338-05:002009-12-30T19:22:25.338-05:00When dinosaurs roamed the earth, software docs cam...When dinosaurs roamed the earth, software docs came in two pieces: A user manual, and a reference manual. The user manual was a tutorial or overview of the software, usually having an introduction and then chapters that might be, for example, "Starting xyz" "Saving your work" "Interfacing xyz with foobaz," etc. It would not cover every feature, but it covered in broad strokes what the software could do with enough detail to be useful to someone wondering just how it could be used.<br /><br />The reference manual was organized by command, or opcode, or etc., and listed in great detail what each piece was, with all of its options and details of how it worked. You weren't expected to be able to learn how to use xyz from ground zero if you only had the reference manual, but it was the go-to place once you knew how to use it and were looking for details.<br /><br />In language terms, the reference manual was like a dictionary, and the user manual like a grammar guide with some sample sentences.<br /><br />I wonder if that split isn't still a good idea not just for the user, but for the author.Wayne Conradhttps://www.blogger.com/profile/10595005905880642013noreply@blogger.comtag:blogger.com,1999:blog-19727408.post-54399705125394476022009-12-29T08:52:31.098-05:002009-12-29T08:52:31.098-05:00Not Counting On Miracles - I nuked your post due t...Not Counting On Miracles - I nuked your post due to _language_...if you want to rant about Austin, please do so without four letter words.Benjamin Supnikhttps://www.blogger.com/profile/04886313844644521178noreply@blogger.comtag:blogger.com,1999:blog-19727408.post-63046326115497019112009-12-29T04:27:30.573-05:002009-12-29T04:27:30.573-05:00This comment has been removed by a blog administrator.Not Counting on Miraclesnoreply@blogger.comtag:blogger.com,1999:blog-19727408.post-22320732389280774102009-12-28T19:41:08.252-05:002009-12-28T19:41:08.252-05:00I'm thinking of updating my FSX KML scenery to...I'm thinking of updating my FSX KML scenery tool to work with XPlane so<br />updated documentation will be much appreciated!<br /><br />Regards, Matthew.Anonymousnoreply@blogger.comtag:blogger.com,1999:blog-19727408.post-569365378163597022009-12-28T09:52:00.366-05:002009-12-28T09:52:00.366-05:00Usually, one hunts for the Eureka line all over th...Usually, one hunts for the Eureka line all over the web, and not just the documentation. Like the keystone of an arch, when the Eureka line is missing, nothing will work; the picture is not whole. And yet, the Eureka line is the one most often assumed to be too obvious to mention.Anonymousnoreply@blogger.comtag:blogger.com,1999:blog-19727408.post-16993254812953839482009-12-27T18:04:48.223-05:002009-12-27T18:04:48.223-05:00Ben, this epiphany is a godsend to all X-Plane hob...Ben, this epiphany is a godsend to all X-Plane hobbyists - an excellent holiday present, if you will. I know this is a bear, I've had to translate code into human concepts too. User-think is a whole 'nuther world from Developer-think. It will take time...but if this becomes the way of things with Laminar, X-Plane will only grow faster. Cheers, and good luck!Stevenoreply@blogger.comtag:blogger.com,1999:blog-19727408.post-9185068930570935092009-12-27T14:42:57.045-05:002009-12-27T14:42:57.045-05:00How many computer people does it take to change a ...How many computer people does it take to change a light bulb?<br /><br />30 - One to analyse the existing light bulb installation, one to specify the new installation, one to implement it, five to beta test and twenty-two to write the damn documentation!<br /><br />Seriously though, as a coder who worked in education I can sympathise. Your docs have to contain all the necessary information working on the assumption that the end user knows absolutely nothing while managing not to sound patronising - It is never easy. Good luck :)Anonymousnoreply@blogger.com