Jump to content
  • Advertisement
Sign in to follow this  
Telastyn

Documentation for review

This topic is 2441 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Recommended Posts

After my first post about the difficulty in debugging Tangent, I got a lot of good advice about how to rework my development process to be more robust. The first and foremost was the deceptively obvious: 'less complex code is easier to debug'. The painful debugging was maybe just a symptom of the fact that I wasn't working on the project. The painful debugging, the slow 'pick it back up' learning curve, the lack of actual progress are all disincentives to make it go.

Part of the problem after some thought is the lack of requirements. I'm the only one working on the thing, but as it grows it's gotten to the point where I can't keep what is current in my head; especially after months of not thinking/working on it. Good process is good process regardless of the project, so I've set into writing up a specification for the language. I think that will help me more easily pick up where I left off, and will provide a better view of what needs to be done so when I venture into making the code less complex it will be done better. It should also aid in writing more/better tests since the expected behavior will be better defined.

Unfortunately, I don't have a great idea if the specification is particularly good. I'm writing it, and I am familiar with the concepts it's trying to spell out so do not have a good objective view of how well it communicates information.

I've modelled the document off of the C# spec. It's not yet into the nitty gritty of the spec, but I wanted to get eyes in front of the document before I got far into it only to realize it was horrible.

Can I get a handful of people with varying levels/types of experience to take a look at the spec as it stands and provide some feedback please?

Mostly I'm looking for documentation issues (hard to follow, not clear, bad organization) but any feedback will be valuable. Thanks in advance.

Share this post


Link to post
Share on other sites
Advertisement
I just skimmed over your documentation without reading it in every detail. I quite like the hello world-example at the beginning, but then I find it a bit confusing, because it jumps straight to some advanced coding stuff without covering the basics first. In the "Types" and Phrases" section you make use of classes and operators, but they are only explained later in the document. Also I split up the where is X-part and put the differences to C# into each subsection, like constructors go into the "Classes" section.

I would suggest a structure more like this:

  1. Intro / Getting started
  2. Rough Overview of the differences to C#
  3. *simple* types
  4. Classes and Namespaces
  5. Enumerations
  6. Control structures / absence of these
  7. Your original "Types" section

I hope this helps you a bit.

Share this post


Link to post
Share on other sites
Thanks for the feeback, my concern is that everything works based off of type info. Leaving that crucial difference until the end seems like it would cause a lot of confusion.

Share this post


Link to post
Share on other sites
The doc has been expanded and is starting to get into more of the nitty gritty. Next to come is details about parsing and then expression analysis. I also discovered some issues when actually spelling things out; mostly around how field/method modifiers are declared.

Abstact fields:


foo => class {
bar : int = abstract;
};


Abstract methods:


foo => class {
(this).bar() => void;
};


Private members:


foo => class {
private {
bar: int;
(this).baz() => int { return bar; };
}
};

Share this post


Link to post
Share on other sites
Added how the language should turn a sequence of tokens into a syntax tree, re-ordered some things, how specifically ambiguity is resolved (if possible).

.doc
.html

Share this post


Link to post
Share on other sites
I haven't had time to review in depth yet, but one very important piece of advice I can offer (as a Programmer-Writer at Microsoft) is to always plan and write with your audience in clear view -- As a language specification your audience is ianguage implementers, and perhaps advanced programmers -- granted that, as a largely experimental and academic language currently, you aren't likely to have language users (in the mainstream sense) as an audience yet, but you should still plan and write documentation as if the various groups exist and are distinct.

There might be a minimal amount of guidance in a specification, necessary to set the stage and illustrate the concepts in code, but if it gets to be a great deal, starts to feel detached from the surrounding specification, or begins to feel "prescriptive", then you might consider also having a "Tangent Users Guide" alongside the "Tangent Language Specification". They could exist in the same document of course, its just that they should be in distinct sections.

Another reality to be aware of is that, frankly, not everything fits into a neat hierarchy, so don't sweat the details of what-goes-where -- put things where they feel right, and move them if things change. This echoes the Google mantra of "Search, don't sort" -- clearly many things will fit into a structure, but sooner or later you're going to find things that don't fit neatly into one bucket or the other.

Some editorial tips:
- Use precise language (ex. Don't say "... the function may return an error code" unless you're giving permission, use "might" if you mean to say "its possible that...")
- Use consistent language.
- Avoid idioms and expressions from your mother tongue (or any other, except maybe latin)
- Avoid jargon unless it's widely known, and even then define it the first time.
- Choose a consistent voice (first, second or third person, active or passive, present or past tense) -- At work, it's second-person, active, present tense -- that's common for technical publications
- Prefer plain, unambiguous language (ex. instead of "... a single person can do X" use "... just one person can do X")
- Clarify ambiguous specifiers -- don't use 'it' to refer to something unless there can only be one 'it' in the sentence/paragraph.
- Avoid contrived examples -- hallmarks of this are identifiers like 'foo' and 'bar'.

Share this post


Link to post
Share on other sites
Sign in to follow this  

  • Advertisement
×

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

GameDev.net is your game development community. Create an account for your GameDev Portfolio and participate in the largest developer community in the games industry.

Sign me up!