guides

[MatthewSteen]

Add user guide from https://bas-im.emcs.cornell.edu/223/223standard/-/wikis/User-Guide.

Issue to discuss what files/pages to include in the top level Guides section.

https://diataxis.fr/tutorials-how-to/#understanding-the-distinction

A how-to guide’s purpose is to help the already-competent user perform a particular task correctly.

FYI @lazlop, @pdelgosha22, @steveraysteveray, @gtfierro

[lazlop]

@MatthewSteen Our idea for a user guide might be closer to a reference guide than a how-to guide. I'm going to try and fit things into the diataxis framework but I may need your help.

[MatthewSteen]

@lazlop sure, feel free to git mv the guides/user_guide.md if you feel it fits better with Diataxis. Should probably consider renaming to user_reference.md too in that case.

Do you think a User Guide/Reference might be too long and could be more easily followed by breaking up into smaller parts?

[lazlop]

Yes I'll try breaking it up. Can you add me to the repo, or should I take out a fork?

[MatthewSteen]

Added you with write permission, let me know if you need more.

[lazlop]

I've been trying to add mermaid parsing, so that we can easily create graph diagrams inline. I just noticed that there's a difference in syntax between gh-pages and github, that should be reconciled in the future.

This is out for decision but seems to have been reviewed jupyter/enhancement-proposals#101

I may create another issue reminding me to update documentation when that change is made.

[MatthewSteen]

Here are the ones that were listed in the intro.md (landing/root page), which I'll remove from there.

• Guides
  • How to Model
    • Connectivity
      • Mediums
    • Containment
    • FunctionBlocks and Controllers
    • Sensors and Actuators
    • Properties and Aspects
  • How to Access Telemtry Data
  • BACnet as example
  • How to Extend the Standard
    • Describing G36