Showing posts with label technical documentation. Show all posts
Showing posts with label technical documentation. Show all posts

Friday, July 14, 2017

AutoDoc: We Automated Product Documentation

Geppetto's AutoDoc

Gumstix has announced this week that Geppetto users can now download documentation for their designs that is generated from the current state of their project.  The addition of the AutoDoc button marks the public release of a tool we've been using internally for some time.  As one of the content curators of this application, I'm excited to share it with everyone because it's a bigger deal than it sounds.

Hardware Documentation

I'm one of those people who find it satisfying to produce usable technical documentation - to describe the operation and setup of a platform in a legible, accurate and eloquent way.  I have always felt that written tech materials either skimp on details or skimp on readability, and I strive to find a balance of both.

For hardware, one of the documents engineers find most helpful is the schematic - a block diagram of the ICs and passive elements that are interconnected in a design.  Firmware programmers, on the other hand, are less reliant on these drawings.  Instead, they need to know the bus names, addresses, GPIO indexes, and features  of the devices connected to the SoC they are programming.
Both need access to technical reference manuals, a layout overview, and connection maps.

AutoDoc cover page for one of my designs
Geppetto's purpose is to provide an avenue for board development that does not require in-house electrical engineers, providing a piece of hardware that could pass directly into a developer's hands.  In my opinion, this is the epitome of the startup use-case.

Why AutoDoc?

Because Geppetto completes the layout, BOM, and fabrication steps for your design, you can have a board in your hands really fast.  That doesn't leave a lot of time for someone like me to sit down and write out a detailed description of your design and its components, so we developed a method of generating written design specs solely from the data later used to generate your board.  We have been able to provide this kind of documentation for some time and it has helped many clients get their applications up and running fast.

With the data in these files, developers can configure drivers, write interface software, and begin testing code before the board has even shipped.  By exposing access to this resource to you before you complete your design, you don't even need to order your boards before you get started. Clicking on the AutoDoc button gives you the pin-outs and signals as they are currently saved.  I feel like it's empowering you with ownership of your design at the earliest possible time.

...And I don't have to sit there and write it all out.

Board layout diagram and a module description

Why it Works

If you don't know what LaTeX is, you should.  It is essentially a programming language for documents.  Look at this way:  When you write a document in MS Word or Google Docs, you have to struggle with the complexity of its "What You See is What You Get" (WYSIWYG) interface.  This is nice for letters, memos, and most resumees, but when it comes to technical documentation, it becomes a fight.  Also, it's not particularly portable.  When you create a document in Google and download it as a .docx file, it definitely doesn't look the same.  Margins change, images move or disappear entirely, fonts are lost or mutilated...  A mess.

Tables, captions, title pages, pagination and indenting:  All these things can be hard-coded into a document with LaTeX.  It will look right every time you compile it.  It will look right when someone else compiles it.

So if we treat documentation as source, then we can script it.  We can apply templates to it. We can make the result deterministic and incrementally improve its quality and content.  And this is what we did with AutoDoc.  There is now no temporal or financial expense in creating a useful reference manual for custom designed Geppetto boards  Enjoy.

What's Next?

I like how Geppetto automates things.  Seeing what it delivers always makes me smile.  So what else can we automate.  Lots!  What else do you need, as firmware developers?  As project managers?  As startup companies?  You can look forward to more of it from Geppetto.