Sign in to follow this  
thre3dee

Documenting a language

Recommended Posts

Hi, As you may know I'm developing a scripting language called GorillaScript. I was wondering if anyone knew of any information on how to best document a programming language, including things like how to split up the documentation and what parts to explain as I'm currently using the Lua documentation as a guide. I'd like to do an MSDN style documentation set, but the HelpStudio software only exports to MShelp 2 in the Lite version, so I can't rly use that. Any ideas?

Share this post


Link to post
Share on other sites
Well, first, some more online examples: Caml Light, O'Caml, Felix, PHP, PERL, python.

A format I like a lot is compiled HTML (locally) and normal HTML with a search function (online). I can get away pretty well with a man page as well.

As for the contents, most online documentations have four different sections:

  • A "quick start" guide which describes in casual terms the main features, principles and idioms of the language to a new user. This usually involves tutorials, install instructions and very little advanced topics.
  • A "language features" guide which will explain how the language works and should be used, along with details about common compiler errors, small specificities of certain principles, and so on. It's still designed to be learning material.
  • A "language reference" document, which contains everything that is necessary to roll out your own compiler for the language. This includes the exact tokens and grammar, the rules for checking, scoping, binding, evaluation, conversion, calling, bytecode generation, evaluation order, undefined behaviour and so on. This is definitely not learning manual, but rather a reference (you refer to it to check a specific thing you're doing).
  • A "language libraries" document describing the various libraries provided with the language. This can also include interaction with other languages and how to create a library.


Share this post


Link to post
Share on other sites
Thanks a lot. I had already started the documentation but I only had a vague idea of what I needed to document.

Sounds like more work than I originally thought but hey if I put the hard yards in I'll get that much more out of it...

Cheers

Share this post


Link to post
Share on other sites
I tend to prefer manuals and tutorial material to also be in PDF format for offline viewing/printing.

Lua is a good guide. Most important aspects IMO:

1) Full explanation of syntax and semantics of language (with examples).

2) Detailed explanation of FFI, with a large example showing all aspects.

3) Tutorial - working from first principles up to a reasonably large (but simple) program.

(4) A central place for user-submitted tutorials, articles and samples - this is useful for anyone coming to a new language, searching Google is easy but not always that efficient at finding good resources.

Share this post


Link to post
Share on other sites
Quote:
Original post by thre3dee
Hi,

As you may know I'm developing a scripting language called GorillaScript.

I was wondering if anyone knew of any information on how to best document a programming language, including things like how to split up the documentation and what parts to explain as I'm currently using the Lua documentation as a guide.

I'd like to do an MSDN style documentation set, but the HelpStudio software only exports to MShelp 2 in the Lite version, so I can't rly use that.

Any ideas?





Lots (and lots) of examples...

Hyperlinks and especially links to 'see also'.

I remember how useful Borlands docs were when you were trying to figure out what you needed to do something you didnt know the name of. (ditto on MAN pages..)









Share this post


Link to post
Share on other sites
Well I've currently got 13 example scripts in the "examples" folder showing off each major part of the language with full commenting.

And I'm going to have some tutorials on how to use the API as well as doing certain things in the language such as protocols.

Plus I found an awesome free program for making detailed documentation files which outputs to CHM and HTML (with a sidebar TOC). It seems very polished for a free one considering they're all over $200 to get a license for. HelpNDoc

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

Sign in to follow this