search

homieiot / convention

šŸ” The Homie Convention: a lightweight MQTT convention for the IoT
https://homieiot.github.io/
Other
710 stars 59 forks source link

Restructure spec #149

Closed andig closed 4 years ago

andig commented 5 years ago

After working with the spec a bit now I've found it a bit inaccessible in terms of "important things first". As-is:

  1. Abstract
  2. MQTT Restrictions
  3. Base Topic
  4. Timings
  5. Extensions
  6. Topology

I could imagine the following order would be easier to digest:

  1. Abstract
  2. Topology
  3. Base Topic -> remove, this is already part of Topology
  4. Extensions
  5. Timings
  6. MQTT Restrictions

if there's interest in this I'd be happy to do a PR.

davidgraeff commented 5 years ago

The website does not reflect the specification 1:1, so this issue is about the website generator.

Because homie has multiple versions, we decided that it makes sense to have a unified document preface which contains all MQTT restrictions, faq, and generic topics.

This preface can of course also be appended instead of prepended.

andig commented 5 years ago

The website does not reflect the specification 1:1, so this issue is about the website generator.

Note sure what that means: https://homieiot.github.io/specification/ claims to be the spec? Is there another one?

Because homie has multiple versions, we decided that it makes sense to have a unified document preface which contains all MQTT restrictions, faq, and generic topics.

Totally! I'm just saying its hard to get the spirit of homie since the reading starts with technical details instead of the bigger picture.

Feel free to close or let me know if you want a PR.

davidgraeff commented 5 years ago

I have the same feeling actually, but if you read any scientific paper or IEEE specification or IETF specification, they all start with the preconditions (the boring parts). That's why I have the example on the landing page of the homie website.

I thought about maybe collapsing those parts, like it is done with the FAQ.

Note sure what that means: https://homieiot.github.io/specification/ claims to be the spec? Is there another one?

The website generator takes all spec versions of this repo, generates a unified preface out of the latest version and generates a page for each version with the preface prepended. The preface sections are not the order as how they appear in the convention.md file here on the repo though. Extensions is at the end in the convention.md file for example, but because it is a preface section it moves to the front on the website.

andig commented 4 years ago

Closing as I didnā€˜t figure out a good approach to do this with the generator.