Sawppy Documentation Suggestion: BOM and UML

I had the dream of a documentation system for Sawppy that doesn’t seem to fit anything out-of-the-box, but I had the chance to ask a group of documentation experts for what they thought might apply. It looks like DITA is the super flexible Swiss army knife for documentation. It is a free open standard, but the only freely available DITA software tool I could find works at a low level and I would have to put in a lot of time to build up the system I dream of. In addition, some of the problems I wanted to solve edge into other well-established problem areas.

Bill of Materials

Similar to documentation, the challenge of tracking parts and components is well-tread ground for engineering projects. People at the meeting with industry experience suggested a few terms. MRP or Materials Resource & Planning was one, plus several variants on BOM or Bill of Materials. This area is big business! Sadly free open source tools are scarce. Someone gave a pointer to OpenBOM.com but upon further research I was disappointed to find that despite the name, this tool is not actually open.

That leaves us with few choices between “use a spreadsheet” and big ticket enterprise software. Even if numerous choices were available, such tools are focused on a very small subset of the overall problem. I do want to set up some kind of parts management, but bringing in a full fledged BOM tool adds a lot of complexity I’m not sure is justified for a small scale project like Sawppy.

Model All The Things

I had the same concern about another series of suggestions: fully model everything about Sawppy using a modeling language like SysML or PlantUML. I agree doing so will result in a complete picture, breaking down every part of the rover project. Such data could then feed into software packages that generate visualizations plotting dependencies between components. That sounds good, but the amount of work also felt disproportionate to the benefit it would bring to a project of this scale.


What I hoped would be a better fit for a project of Sawppy’s scale are the documentation systems already available for open-source software projects. While they would not have some of the hardware-focused features — such as BOM or UML above — they are more approachable than DITA and promise to be amenable to customizations. Perhaps even to give a lightweight subset of big BOM and UML tools.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s