41–50 of 58 posts
Yes please. Documentation is so under developed. Most engineers funny know how to create it. This should be a critical skill that is covered with multiple full length classes in college. Learning how to write good docs will teach you how to write good code
If you are in a rush, the diagram is all you really need. The lecture is needlessly long, even played at double speed.
In case you went "hey, this looks like a blatant rip-off of Divio's pages, doesn't it?" -- yeah it is, because this is the spin-off of that particular aspect from Divio.
wait so... this is a spinoff startup? i didnt even know what Divio sells..
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
Feel free to ask me more.
I've been trying to apply this approach, and it's generaly been a useful way of forming a holistic view of your docs. The only quadrant that can be a bit challenging is the explanation: some projects are just relatively straightforward and don't require a lot of background knowledge about the whys. In that case, I've found it best to just stick to a couple of lines on the homepage explaining the project's background…
The scheme is not a plan that must be fulfilled, it's a guide or map to help you see where you are and where you need to go.
However, don't be ashamed of barren-looking things. They are OK. The reader won't mind.
"It should exist".
I've been trying to apply this approach, and it's generaly been a useful way of forming a holistic view of your docs. The only quadrant that can be a bit challenging is the explanation: some projects are just relatively straightforward and don't require a lot of background knowledge about the whys. In that case, I've found it best to just stick to a couple of lines on the homepage explaining the project's background…
Usually, I realize it is because it's following whatever is my framework's way of doing things, or it is following the usual specs of the tools I use. In this case, I make a conscious effort to dig up a link to a tutorial on a "standard project", and link it there, an example would be:
> This project is following a Classic Java Spring Architecture (-> links to the spring tutorial), with this and this modification...
You have to imagine that people happening upon your documentation might have a totally life experience than you, they may even be a lowly intern, thrown to your project as the sole maintainer of your code, with only school-taught experience.
It's funny how little things have changed since software documentation started. Have a look at the Guideline for Software Documentation Management (1984 https://nvlpubs.nist.gov/nistpubs/Legacy/FIPS/fipspub105.pdf ) Documentation fulfills five important functions: - Communications to management about the progress of the project, providing intermediate product visibility - Task-to-task communication - Instruction and…
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 e…
To be fair, when the article was posted under its Divio url a year ago it got 717 likes and 199 comments - https://news.ycombinator.com/item?id=21289832
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.
Some personal rules for docs: 1. Explain, in plain non-jargon words (nobody cares how smart you are) what problem is being solved, how, and why. 2. Provide contextualized examples (no foobar), not making assumptions about what the reader knows or doesn't know (and avoiding condescending language like "it's easy," "it's common sense" or anything that suggests the reader is "dumb" if they don't get it). 3. Think in ter…
It may be due the language barrier or something but there are some phrasing that really throws me of: > You might send variables to this server function by calling this endpoint from your javascript code. You might but in fact you must (or you can) because it is the only way send variables to the server from Javascript. It's not like it's a personal preference or that there is another way. > You can choose to use `re…
Values (being data) can be transmitted, actual variables (being programming-language constructs to contain values and make them available to operate upon) cannot.
I love this doc because while it's not staying the whole story, it was basically my conclusion as well: you can't have one doc, you need several of them for different use cases. I would had to the mix a page where jargon is defined, like a lexicon. You cannot, and should not always get away with jargon. Sometime you should (beginner tutorial), sometime you should define it inline (advanced tutorial), and sometime you…