search

open223 / docs.open223.info

ASHRAE 223P User Documentation
https://docs.open223.info/
2 stars 1 forks source link

guides #1

Open MatthewSteen opened 9 months ago

MatthewSteen commented 9 months ago

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 commented 9 months ago

@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 commented 9 months ago

@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 commented 9 months ago

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

MatthewSteen commented 9 months ago

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

lazlop commented 9 months ago

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 https://github.com/jupyter/enhancement-proposals/pull/101

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

MatthewSteen commented 9 months ago

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