Re: Writing Documentation

Philip Herron <herron.philip@googlemail.com>
Tue, 16 Feb 2010 00:38:45 +0000

          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: Philip Herron <herron.philip@googlemail.com>
Newsgroups: comp.compilers
Date: Tue, 16 Feb 2010 00:38:45 +0000
Organization: Compilers Central
References: 10-02-041 10-02-048
Keywords: documentation, books
Posted-Date: 16 Feb 2010 10:28:15 EST

On Wed, 2010-02-10 at 16:34 -0600, jgd@cix.compulink.co.uk wrote:
> Even in a thesis, it may well be appropriate to start with a brief
> tutorial to introduce the basic concepts of the language. Then one needs
> to describe each concept and each construct clearly, although probably
> in rather less detail than a language standard would.
>
> For examples, your best bet look at successful published books: the
> tutorial in _The C programming Language_ by Kernigan & Ritchie is
> noticeably good and has been imitated several times.


Hey


Thanks for the pointer to that book I haven't read it, but i have
ordered a copy from Amazon. Its quite hard to write documentation on
this subject, there are so many ways to do it and i just think its nice
to get some guidance from you guys here since its my first time!.


So far I have a structure in the thesis of:


-Origins
--Design Principles
--Why a new Language


-Language Specification
--Lexical Tokens
--Typing
--Functions
--Expressions
--....


-Implementation Architecture
--....


-Language Examples
--Project-A
--...


-Conclusions
....


Does this seem like a good idea so far? I've been keeping the language
spec similar to the Google Go language spec and Python lang-spec docs.
Then i go into more details when I explain the implementation with
plenty of examples to show what happens.


Though i am thinking i might change that to a tutorial style section and
build some small programs.


Thanks anyways!


--Phil



Post a followup to this message

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