Re: Writing Documentation

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.

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