Divio is a cloud management/application hosting platform. We use Docker for containerisation, and provide a unified integration layer to multiple different underlying vendors (AWS, Azure, etc).
It means you can use the same tools (Control Panel, CLI, API) to create and manage cloud applications and their infrastructures on all those different vendors.
The idea is that Divio takes care of infrastructure/DevOps concerns so that customers can concentrate on developing applications and products. https://www.divio.com
i personally dont have this need at all (all in on AWS, and am ex Netlify and very friendly with Render) so havent really needed a unified integration for multiple vendors. good luck!
Hi everyone. I'm Daniele, author of the framework.
It now has its own domain, because it's about time. This is where it will continue to be updated and maintained.
A quick clarification: I am still at Divio, but after a break in June I'll be looking for something new.
If you have a notable product, a large developer user-base, a positive internal culture, and need to address some significant challenges in developer education/documentation, at the highest level - get in touch: daniele@vurt.org
I'll not repost the comment I made on that thread (because: too many spammy links) but the advice in the article is good; I wish more people would follow the recommendations.
So far, it's only dependent upon luminosity - as long as it's not 0, it's considered ruined. And in reality, the unexposed frames wouldn't be ruined either (that's easy enough to model).
I started exploring a graphical user interface too, using Anvil - https://camera.anvil.app. It only has two controls so far, but it's simply a matter of adding form elements and output for the existing objects.
Perfect example (in the scheme) of an explanation/background/key concepts/discussion/whatever you call it document.
That's where you weigh up options, discuss alternatives, etc. If it's something you could read about in the bath or talk about over dinner, it goes there.
Perhaps, but I'm not sure it's so clear cut. The best practice should be concrete - it should have code examples. It should be beginner friendly (since it's beginners who will use it most often).
That's really great to see it used in Gatsby's documentation, I wasn't aware of that. And I like the way you say e.g. "Practical step-by-step guides to help you achieve a specific goal. Most useful when you're trying to get something done." under each heading, it hadn't occurred to me that it would be good to state that explicitly like that.
To complete the circle, https://divio.com is built in Gatsby (not the documentation though; that's in RST/Sphinx and published on readthedocs.com).
You are quite right, there are various things that aren't included in the scheme, that ought to be included in a complete set of documentation.
Other examples could be: release notes (though you could include them in reference), contribution guide (though it could be part of how-to) and of course, the Introduction you mention.
Mostly I think that these things probably belong outside the scheme, in the same way that say an appendix or an introduction falls outside main body of text in a book.
An introduction (in documentation) is basically marketing: a reason for someone to keep reading.
For me the scheme is not so much a complete list of every kind of thing that must be written (I think it goes without saying that you need to create useful contents tables for example) as a guide to how I should be writing and a reminder why I am writing.
I honestly also think it is worth mentioning introductions as an essential part. I somewhat disagree that it is outside the scope of a scheme of documentation.
An introduction to both the system goals and overall architecture provide essential context for the rest of the documentation, and can even provide the scaffold to structure it around.
It is all too common for writers of documentation (deeply embedded in the project) to forget that the person reading the documentation may have no clue what the whole system is trying to achieve (especially so in public-facing documentation... how many times do you see a link on HN to a documentation page with no explanation of what "a BUZZY GRAPHEME WRANGLER" actually is?).
Also... by your analogy, I am fairly certain that a guide to writing a technical book would dedicate a fairly considerable amount of space to the topic of a good introduction ;)
I don't disagree about the importance of introductions.
I can't count the number of times I've looked at the home page of documentation for some product and it has felt like stumbling into a teenagers' conversation conducted entirely incomprehensible references, slang and in-jokes.
An introduction needs to say what the thing is, what it does and why someone might want to use it. Usually that can be expressed in a few sentences.
I don't really see it as a mode of documentation in the way that the four components I describe are.
I wouldn't worry too much though. The framework isn't intended as a "do this, all this and nothing but this or you're doing it wrong" final statement on the art of documentation.
It's more a tool for thinking about what you are writing, for whom, and how you can best write it for them. It's to be used however someone finds it useful.
> Mostly I think that these things probably belong outside the scheme
Yeah, I think somethings count as "meta documentation" and are "documentation about the documentation" instead of the actual documentation.
"contribution guides" to me are definitely that, "introductions" are mostly that. I reckon licenses are probably "meta documentation" too (since they'll also be in the source code). "release notes" are a bit of a grey area in my head (I'd consider at least major version update release notes and any depreciation/removal of features to be "part of the doco".
Would be interested to know what the experience is of this in other companies, smaller ones as well as large corporations with masses of $$$$ swirling around.
