Re: Writing Documentation

jgd@cix.compulink.co.uk
Tue, 16 Feb 2010 11:47:45 -0600

          From comp.compilers

Related articles
Writing Documentation herron.philip@googlemail.com (Philip Herron) (2010-02-10)
Re: Writing Documentation jgd@cix.compulink.co.uk (2010-02-10)
Re: Writing Documentation herron.philip@googlemail.com (Philip Herron) (2010-02-16)
Re: Writing Documentation jgd@cix.compulink.co.uk (2010-02-16)
| List of all articles for this month |

From: jgd@cix.compulink.co.uk
Newsgroups: comp.compilers
Date: Tue, 16 Feb 2010 11:47:45 -0600
Organization: Compilers Central
References: 10-02-068
Keywords: documentation
Posted-Date: 16 Feb 2010 19:14:36 EST

In article 10-02-068, herron.philip@googlemail.com
(Philip Herron) wrote:


> -Origins
> --Design Principles


What is this going to cover? All the buzzword ideas that you wanted to
include, or something else?


> --Why a new Language


The obvious place to put a short tutorial would seem to be just here. It
allows you to make the subsequent specification terser.


> -Language Specification ...


> Then i go into more details when I explain the implementation with
> plenty of examples to show what happens.


The problem with that is that you're inevitably introducing the idea
into the reader's mind that the behaviour of the examples will depend
significantly on the implementation. This is not a good idea in a
thesis: the examiners will generally be looking for a very clear
division between what is defined by the language and what is defined by
the implementation.


This issue may well not matter so much to the authors of Google Go of
Python, since they expect their implementations to be the major ones
used, but that is not a good assumption for an academic project.


Since you're only one fallible human, more will be defined by the
implementation than you realise, but you should really make the
distinctions you know about clear. Provide examples in the
implementation section of things that you have left as
implementation-dependent, and things where the implementation is complex
or inobvious.


Examples of the language itself would be best placed in your tutorial,
the explanations of the language features, or your example projects.


--
John Dallman, jgd@cix.co.uk, HTML mail is treated as probable spam.



Post a followup to this message

Return to the comp.compilers page.
Search the comp.compilers archives again.