DanieleProcida

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

Feel free to ask me more.

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 should also like to point out that when I posted this a week or so ago, it got just three points https://news.ycombinator.com/item?id=26724825. Very unfair.

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.

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.

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.

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).

Thanks for the kind words!

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.

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.

Not with these servos or this mechanical arrangement, that's for sure. But, it's very interesting to think of ways to improve the precision of imprecise hardware, using only software.

It works fine with every kind of drawing implement I have tried:

* pencil * charcoal * ball-point (needs additional weight on the pen) * roller-ball * felt-tip * fibre-tip

It draws so slowly that there's no issue about waiting for the ink to dry.

But what I like best is soft pencil on slightly textured paper.

Daniele

Full details of the project, including all the code and documentation, are posted at https://www.brachiograph.art.

This is my attempt to do something with the Raspberry Pis and cheap servo motors I've had hanging around that's both genuinely interesting and also as simple and cheap as possible. Robotics isn't my subject, but I wanted to make something.

The total cost of hardware (excluding the clothes-peg, pencil and things you will find in a kitchen drawer) is €14. You could build the whole thing in about an hour, it's a fun thing to do with a child, and they love the fact that it's made from household materials.

One thing I like about it is that it's all 'wrong' - you are not supposed to use servos or electronics like this, and it's not what a 'real' engineer would do - but it still works well enough to be fun.

The cost and simplicity are really important because this project has come with me to events like PyCon Africa (http://pycon.africa) and PyCon Namibia (https://na.pycon.org) where not everyone has easy access to labs and hack-spaces and electronic hobby shops, and many people have to learn and experiment on much smaller budgets.

There's some custom Python code: https://github.com/evildmp/BrachioGraph and contributions and issue reports are welcomed. And it's on Twitter: https://twitter.com/BrachioGraph.

If you build one yourself, please send me a picture!

I do that sometimes too: https://brachiograph.readthedocs.io/en/latest/get-started/in....

I also use "background" or "discussion". Someone else here suggested "rationale".

That is interesting - my experience is the opposite, that how-to guides and tutorials are the most-commonly confused types of documentation. My aim is to make the serve totally different needs:

* tutorials: I'm in charge (the teacher) and I know what the new learner needs to grasp and become comfortable with so that they gain sufficient basic confidence and skills. In the tutorials, the beginner doesn't even know what questions to ask or what language to us when asking questions

* how-to guides: the user is in charge; they are able to formulate the questions, and have the basic confidence and skills. What they need from me are the recipes.

As described, it's the difference between teaching a child to cook, and a book of recipes for somebody who already knows the basics of cooking and the kitchen but wants to know how to cook a particular thing.

If you get teaching a child to cook mixed up with a book of recipes everybody concerned will have a bad time. It matters most for the child, they will never want to learn how to cook with you again.

The same go for tutorials in my experience.

Thanks for all the interest and kind remarks this has received. I have updated the documentation substantially and included more photos in it.

Some more images of and by the plotter: https://www.dropbox.com/s/fuifujd70jvn7lw/brachiograph-image...

Also it's hard to defeat hysteresis in the system, both in the servo motors (they have significant dead bands) and the mechanical arrangement of the arm/pen.

Be careful, a lot of SG90 servos are fakes. Below a certain price, they all appear to be counterfeit.

As far as I can tell, the real ones have four screws in the base, and "TowerPro" printed into the plastic on the top. The fakes have two screws, no brand name moulded into the plastic, and inevitably stop working quite swiftly.

https://brachiograph.readthedocs.io/en/latest/explanation/ha...

More expensive servo motors will produce better results, but past a certain point, they would require more power than the Pi alone can supply.

The mechanical construction also introduces imprecision.

"not useful for a lot except artistic sketches" - what could be more useful than that?!

Turns, out, it's actually very reliable in practice. I'm trying to work out at the moment just how far I can go with more powerful servos: https://raspberrypi.stackexchange.com/a/104662/42583. There are limits, but they seem to be greater than I expected, especially when the only power to the Raspberry Pi is provided by a MacBook.

On GitHub: https://github.com/evildmp/BrachioGraph

It's a full-stack Python/Django service. But the Docker containers are of course portable, so...

I wouldn't even dare comment on what the future of JavaScript will be. I can barely keep up with its recent past.

... and now it should be working. Have fun with the demo. Happy Friday to you too!

We're waiting for a change to propagate.

Worse, it turns out that the glitch was... my mistake.

Thanks for pointing it out!

Can you try again? It is working, but we've had a temporary glitch on DNSimple.

If it doesn't work right away, try http://demo.django-cms.org.

Ouch, so it is. We'll get right on it...

You only need to learn Python if you want to do back-end development. Templating, design, content etc don't require any Python skills - just as you don't need PHP skill to build sites in WordPress.