Add 'Diagramming Guidelines' #59
Conversation
misc/diagrams.md
Outdated
|
|
||
| ## Who is the intended audience | ||
|
|
||
| Before starting your diagram, it’s important to think about your intended audience. Who are you creating the diagram for and who is it meant to help? Your audience will inform the level of detail your diagram requires. For instance, a low-level, “nuts-and-bolts” diagram may be more useful for InfraEng, while higher-level diagrams may be better suited for other stakeholders. |
There was a problem hiding this comment.
Instead of,
may be more useful for InfraEng
what about something more generic like,
may be more useful for engineers
There was a problem hiding this comment.
The text has been updated.
misc/diagrams.md
Outdated
|
|
||
| ## Why do we need diagrams | ||
|
|
||
| Diagrams are useful for communicating the data flow within an application. Diagrams can be particularly helpful for complex data-intensive applications (e.g., [geo-harvester](https://github.com/MITLibraries/geo-harvester/tree/main/docs)). That being said, there are some applications where the flow is simple and straightforward enough to not require a diagram. In these applications, thoughtfully written code can serve as documentation. Diagrams also increase accessibility of our data applications, by serving as another medium through which developers and stakeholders alike can understand the tools we create to support the work of MIT Libraries. |
There was a problem hiding this comment.
I might propose omitting the specific example here, just so these docs don't get brittle? I think "data-intensive applications" is sufficient.
(e.g., geo-harvester)
There was a problem hiding this comment.
Reference has been removed!
There was a problem hiding this comment.
Solid write up. None of my feedback is blocking merge (i.e. you can make changes or not depending on your preference).
I can see potential to add additional sections, such as "how to make your mermaid diagrams accessible" and "where do we use mermaid diagrams", but neither should hold up this up from my perspective.
EngX will take the lead on adding "how to make your mermaid diagrams accessible" as we've talked a lot about that already. The "where" part (mostly pointing out we use mermaid in GitHub and Confluence) can be added at any time.
misc/diagrams.md
Outdated
|
|
||
| ## Who is the intended audience | ||
|
|
||
| Before starting your diagram, it’s important to think about your intended audience. Who are you creating the diagram for and who is it meant to help? Your audience will inform the level of detail your diagram requires. For instance, a low-level, “nuts-and-bolts” diagram may be more useful for InfraEng, while higher-level diagrams may be better suited for other stakeholders. |
misc/diagrams.md
Outdated
|
|
||
| ## Why do we need diagrams | ||
|
|
||
| Diagrams are useful for communicating the data flow within an application. Diagrams can be particularly helpful for complex data-intensive applications (e.g., [geo-harvester](https://github.com/MITLibraries/geo-harvester/tree/main/docs)). That being said, there are some applications where the flow is simple and straightforward enough to not require a diagram. In these applications, thoughtfully written code can serve as documentation. Diagrams also increase accessibility of our data applications, by serving as another medium through which developers and stakeholders alike can understand the tools we create to support the work of MIT Libraries. |
* Update language to be more generalizable * Add section describing "where" diagrams are used
|
Hi all! Please see the latest commit, addressing your comments. Thanks! |
Why these changes are being introduced
Provide guidelines on current best practices for diagramming used by InfraEng and EngX.
How this addresses that need
Add "Diagramming Guidelines" to MIT Developer Documentation Site.
Side effects of this change
NONE