Glorified Plumbing

It’s not a glorious task, but we all need to do it.

Gathering information and sharing knowledge are key aspects of an engineer’s job. It’s easy to add to a wiki or publish a few PDFs into your SharePoint directory. Even fixing bad content on a wiki is simple; You see a problem and you edit the file, or at least leave a quick comment.

Content curation is the hard part.

There are professional librarians, curators, editors, and archivists out in museums, libraries, and universities. They probably exist in research institutes, large law firms, and maybe even in the media industry. They don’t exist in startups with 20-150 people, I should know, we seldom even get a technical author.

Now scale back further, to sites like Glorified Plumbing. Currently, our team is me, myself, and I.

Curation of blog posts is minimal. It’s essentially correcting posts where a commentator has identified an error or omission. I treat my posts mostly like a newspaper or magazine article. It’s already out there; just add an errata comment or perhaps some minor rework.

As for the static content? I am still building it out; it’s evolving, hopefully, into something meaningful. I have a choice when I get a two-hour window to write: blog post or static content?

Having reviewed my content popularity, I’ve decided today (and for the next few weeks) to focus on curation and creating static content. I know, static content doesn’t elicit the same dopamine rush as a viral blog post. That said, my biggest seller is my page about oscilloscope configuration to see I2C. I need to follow up with similar pages. As for blog posts, search engines are sending readers to my post about drawing a timing diagram, so I must to put effort into my pages about drawing tools, as there seems to be a need for that information.

I also have some documentation cleanup to do at work. Notes from early in an investigation on some new technologies include assumptions, TBD (to be decided), and FIX-ME comments.

I am sure you have a few pages you keep thinking need a rewrite. How do you decide the time is right to fix your wiki content? Do you limit yourself to factual repairs? If multiple contributors used different tones and voices, would you restructure and rephrase their work to ensure consistency?

I’d love to know how you manage technical debt outside of your code and schematics. And if anyone convinced their management to hire a curator for documentation, please let me know how you worked that miracle!