05 Jul

Parabolas, Rectangles, Triangles & Snakes (Part 8)

Part 8 – Documentation, the Necessary Evil

Love it or hate it, I’ve already decided documentation is required so you are stuck with it. Code comments and docstrings aside, part of the planned documentation is this series of blog posts (so I can remember what I did basically). Hopefully these demystifying some of the mysteries behind the general methods involved.

For the remainder I’ll leave it up to a readthedocs page to explain the ins and outs for the end user. If you are not familar with readthedocs or RTD for short, it’s basically a free service for hosting documentation for public open source projects. You can link it directly to your Github repo, changing any of the documentation committed within Github, and you’ll automatically trigger an update of the RTD documentation pages.

Read More
25 Jun

Parabolas, Rectangles, Triangles & Snakes (Part 7)

Part 7 – Documentation & Verification, Better Than More Integration?

At some point in any projects life cycle you should start thinking about the need for documentation and verification. This post and probably the next few will be dedicated to exploring these aspects.

As a structural engineer, if you are designing a building you have to produce some drawings, calculations, specifications, etc to describe what is being built, and someone probably needs to check these deliverables. Often the drawings are the only deliverable, so its all the end user ever sees out of your blood sweat and tears. You’ll be judged on this alone if it contains mistakes, omissions, etc. Small omissions can cost you or the client are lot of time or money to put right if the contractor has made no allowance for the items. As an engineer designing something tangible like a building, you simply cannot get away without producing drawings, someone needs to produce your design after all and they are going to need some instructions.

Read More