Dark diagrams make for terrible documentation IMO.
Design structured diagrams, built to increase your team's trust in your docs
41–50 of 83 posts
Re: Design structured diagrams, built to increase your team's trust in your docs
#42What on earth do diagrams have to do with trust in docs? Docs that are useful, accurate, and up to date would increase trust.
We agree - useful, accurate, and up to date docs are what increases trust! We're bringing docs closer to the diagrams to visually explain your system in smaller chunks. We've found docs often accompany diagrams, and they become out of date as soon as they're exported! We think instead of diagrams being in docs, docs should be in the diagram.
Alternatively, they can live together.
For example, I ended up writing this to integrate diagrams and Sphinx. https://github.com/j-martin/sphinx-diagrams
Similarly there's https://pypi.org/project/sphinxcontrib-plantuml/ and https://mermaid-js.github.io/mermaid/#/ (among other similar tools).
Re: Design structured diagrams, built to increase your team's trust in your docs
#43I've always felt that these type of tools shouldn't have a traditional home page with sign up, sign in, etc. If you go to Excalidraw's website, it immediately launches the application for you to start using it. If you need extra features, only then you go to a page that provides details, pricing, etc. This is a beautiful pattern that makes these type of tools a daily habit for people to use. I don't want to create an…
I get that, but they want to collect your email to improve marketing. If the product is strong enough it may not matter. Practically speaking, I think getting user signup info is pretty important.
Pop up a modal after they've been using it for a while. Don't shove it in my face the first time I visit.
Re: Design structured diagrams, built to increase your team's trust in your docs
#44Having fallen back in love with PlantUML recently I’ll never use a proprietary tool that doesn’t have declarative syntax. System diagrams and documentation are a crucial part of any software business and one that is regularly out of date as people end up using tools like draw.io which nobody knows how to get access to or use.
> I’ll never use a proprietary tool that doesn’t have declarative syntax Can you provide an example of what you're referring to?
PlantUML diagrams are generated from plain text, they can easily be embedded in markdown or even in code (I'm sure there's a plug-in for that!)
Plenty of examples here.
Re: Design structured diagrams, built to increase your team's trust in your docs
#45I've always felt that these type of tools shouldn't have a traditional home page with sign up, sign in, etc. If you go to Excalidraw's website, it immediately launches the application for you to start using it. If you need extra features, only then you go to a page that provides details, pricing, etc. This is a beautiful pattern that makes these type of tools a daily habit for people to use. I don't want to create an…
I get that, but they want to collect your email to improve marketing. If the product is strong enough it may not matter. Practically speaking, I think getting user signup info is pretty important.
The thing is, we all know they want our email address so they can market to us, so there’s absolutely zero chance of me ever entering a real email address into that box.
Re: Design structured diagrams, built to increase your team's trust in your docs
#46Having fallen back in love with PlantUML recently I’ll never use a proprietary tool that doesn’t have declarative syntax. System diagrams and documentation are a crucial part of any software business and one that is regularly out of date as people end up using tools like draw.io which nobody knows how to get access to or use.
Wow, this is interesting. Are there any diagramming tools that allow importing PlantUML to display them a little nicer than the examples?
Re: Design structured diagrams, built to increase your team's trust in your docs
#47Having fallen back in love with PlantUML recently I’ll never use a proprietary tool that doesn’t have declarative syntax. System diagrams and documentation are a crucial part of any software business and one that is regularly out of date as people end up using tools like draw.io which nobody knows how to get access to or use.
Wow, this is interesting. Are there any diagramming tools that allow importing PlantUML to display them a little nicer than the examples?
There’s some nicer looking ones here:
Re: Design structured diagrams, built to increase your team's trust in your docs
#48Having fallen back in love with PlantUML recently I’ll never use a proprietary tool that doesn’t have declarative syntax. System diagrams and documentation are a crucial part of any software business and one that is regularly out of date as people end up using tools like draw.io which nobody knows how to get access to or use.
How do people not know how to get or use draw.io? You literally go to draw.io and can use it online.
We're replaced our diagramming with it instead of things like omnigraffle as it means everyone has access to tweak the diagrams without having to buy software (and then buy upgrades and plugins), and by embedding the diagram in the .png there's just one file to keep track of.
Re: Design structured diagrams, built to increase your team's trust in your docs
#49Earlier quoted context omitted.
> I’ll never use a proprietary tool that doesn’t have declarative syntax Can you provide an example of what you're referring to?
PlantUML diagrams are generated from plain text, they can easily be embedded in markdown or even in code (I'm sure there's a plug-in for that!) Plenty of examples here. https://plantuml.com/state-diagram
And importantly, because they're text, they can live in a version-controlled environment. I mainly use them within Confluence, and even there you can diff between versions to see changes.
Re: Design structured diagrams, built to increase your team's trust in your docs
#50Having fallen back in love with PlantUML recently I’ll never use a proprietary tool that doesn’t have declarative syntax. System diagrams and documentation are a crucial part of any software business and one that is regularly out of date as people end up using tools like draw.io which nobody knows how to get access to or use.
How do people not know how to get or use draw.io? You literally go to draw.io and can use it online. We're replaced our diagramming with it instead of things like omnigraffle as it means everyone has access to tweak the diagrams without having to buy software (and then buy upgrades and plugins), and by embedding the diagram in the .png there's just one file to keep track of.
I've worked at places where people have exported draw.io as PNG/PDF on internal wikis for diagrams. But what happens when you want to change it? You then have to track down the people who made them, and get access yourself - or find it buried on someone's google drive.
With PlantUML you usually commit your diagram's text syntax to VCS, often close to the code.
As far as usability, we're never going to agree. I find it tedious, compared to writing predictable declarative syntax.