apiaryio / mson

Markdown Syntax for Object Notation
MIT License
900 stars 180 forks source link

What is the benefit of having many ways to express the same? #57

Open w-vi opened 8 years ago

w-vi commented 8 years ago

These two Blueprints, well MSON descriptions produce the very same result and I am wondering why there are two ways of describing the same thing. What's the rationale, wouldn't the language benefit from being simpler and in a sense more rigid? I feel that it makes the life worse as I can mix the stuff and make it even harder to read. Having just one way of doing things means less cognitive load, lower complexity in parsing and therefore less buggy tools.

# Data Structures

## A
+ x
+ y
    + z
# Data Structures

## A

## Properties
+ x
+ y
  + Properties
      + z
zdne commented 8 years ago

I will try to answer with example.


# Data Structures

## A

Description of A
- a
- b
- c

## Properties
+ x
+ y

  Description of y
  - d
  - e
  - f

  ... still description of y

  + Properties
      + z

Does this clarify?

w-vi commented 8 years ago

I still could do it this way (see below) with same result, am I correct? So I will never use the ## Properties construct. I understand why I have the + Properties there, it would be impossible to distinguish it from a description containing a list but why ## Properties ?

# Data Structures

## A

Description of A
- a
- b
- c
+ Properties
    + x
    + y

       Description of y
       - d
       - e
       - f

        ... still description of y

      + Properties
          + z