John's Blog

So much stuff to write about, so little time...

User Tools

Site Tools


Sat Jan 28 - Sim Docs - cont.

Why am I so jazzed up about sim docs? It can't be that hard, just start writing. Right? Not so much.

Aircraft (and sims) are too complex to put all the technical information in one book. They have many different systems and there are many different document types, or doc types: wiring diagrams, parts books, operating manuals, troubleshooting guides, etc. My F-16 experience was hard-bound books. The various avionic systems over which I was lord and master each had their own collection of doc types. It was literally a library.

I'll replicate the F-16 model to a certain extent. By the way, from this point forward I'm going to shorten sim docs to a single word: simdocs. I'll create a collection of manuals that will mature as I work through the project. They'll be electronic, not paper. Anyone will be able to read them by using a browser.

With structure and format out of the way there's one last thing to cover re: tech docs and that is consistency. In the tech doc space nothing irks me more than inconsistent naming of things. Give an item a name and use that name every time the item is mentioned. Time will tell how consistent I am.

My first stab at simdocs was the 'all eggs in one basket' approach. I had one Word document littered with bookmarks so that I could jump from place to place within the doc. It soon became unwieldly so I abandoned the effort.

My second stab was to use my blogging software to create a handful of small books. I recently took them off the web and zipped them up, they're lying (did I get it right, Bob?) around here somewhere. I'll have to find it so I can reuse the good parts. To my eyes the blogging software never looked right and it was painful to use.

This time around I think I found the right software for simdocs. It's called Sphinx. Here's what it looks like. Take a look then come back.

I think it looks clean and uncluttered. Sphinx was created to make it easier for software developers to document their code but it has since been extended to support tech docs in general. A web site named “Read the Docs” serves over 55 million pages of docs a month for over 80,000 projects. For free. All created using Sphinx. This project has a bunch of pages and sets a good example for simdocs.

If I can't make Sphinx work I'm doing something wrong.

I could create a free account on Read the Docs and put my simdocs there but they'd have advertisements. I don't want ads so I dug deeper and learned it'd be much easier for me to put the simdocs on my web server with no ads.

So the last few days I've been learning about Sphinx. I've also been spitballing ideas on how to manage document versions. I think a good idea (since I can explain it easily enough) is to have just one version, the latest version. I can't think of a reason why I'd need to go back to a previous version of any simdoc. I may regret this decision but I doubt it.

So my next step in building the sim is to make a home for simdocs by creating a secure web address for simdocs. I'll put at least one page out there with at least one picture in it. This will let me develop a work flow so I can effectively go from an idea to documentation. Stay tuned.

2023/01/28 19:09 · john · 0 Comments

Sat Jan 28 - Sim Docs

I've wandered around the internet collecting ideas about flight sims. They come in all shapes and sizes. Some fill a garage or an entire room. Some have very high fidelity to the real thing where the builder chose one particular aircraft and duplicated it as closely as possible. Some sims actually roll you around and upside down. That's a recipe for a lost meal. every. single. time. I'd. use it.

There's one aspect of building a home sim that I see pop up from time to time on the forums: documentation. A builder will lament that they have to change something, add something, or fix something and they gotta dig into it to try to remember what they did. Or the builder has passed on and no one knows how to use the thing or how it should be moved.

I'm not going to do that. I'll design and build a sim and write docs to go with it.

A while ago I took a stab at writing sim docs but I never got comfortable with the process or the results. I need this second time to be the last time. My gold standard for manuals are the docs for the F-16. They used the MIDAS system: Maintenance Integrated Data Access System. Once I became familiar with the system (and it didn't take me long to do that) I could jump from doc type to doc type with ease. I may never get there with my sim docs but I'm going to try.

Why not just build the thing and write it all down later? Because if I do I'll never write anything down. Plus, I'm sick in that I sorta enjoy reading well-written tech docs. I never like Caterpillar's and in my decade of travel from dealer to dealer I don't recall seeing a technician pick up a book. When I asked why I almost always got the same answer, “Because they're not very good.”

Fair warning, I'll continue this subject in my next article.

2023/01/28 18:01 · john · 0 Comments

Sat Jan 28 - The Next Big Thing

The next big thing is the flight sim.

Even though I've been bangin' on about buildin' a sim for ages, I consider this article to be project kickoff. But before I type another word about the project I'll share this quote from The Zen of Python:

If the implementation is hard to explain, it's a bad idea.

It's true that that pearl of wisdom applies to writing software but it may have relevance to this project. With that in mind I've created just three (three!) project constraints, everything else is open season. They are:

  1. I shall do my best to keep things simple or at least describe them as simply as possible.
  2. I'll document the project here on the blog.
  3. I'll complete the project in stages or it'll never get off the ground.

Ladies and gentlemen, please set your seats and tray-tables to their full upright positions, grab a-hold of something solid, and hang on.

2023/01/28 17:07 · john · 0 Comments

Sat Jan 28 - Dead Poet's Swag

A keychain, a stickah, and a hurkin' big magnet for the ole' icebox:

Dead Poet's Swag

2023/01/28 16:30 · john · 0 Comments

Sat Jan 28 - Craft Room Electric - It's a Wrap

My goal was to have this project finished by the end of January. I made it with a few days to spare.

In this first picture I show the outer heater shell connected to the small junction box with what electricians call a whip. I made the whip long enough so that the heater can be removed from the wooden box and set on the floor for servicing:

Here's the heater installed and ready to go:

Kim will eventually paint that plaster wall, not sure about the wooden walls. Once upon a time she mentioned covering those with fabric. Right now she's working on a quilt for a sibling and she's committed to get that done first, then continue with the basement craft room.

Whenever I install an appliance like this heater I like to take a look inside the wiring and see what's going on. I paid for a 2,000 watt heater (according to package and product labels) but I'm thinking that may not be what I installed:

That's a little low...
The last time I multiplied 240 x 7.7 I got 1,800 which ain't 2,000. The heater heats the room nice enough so I have a few choices on what to do about the low wattage. I can take the heater back to the store and have it out with customer service or I can forget about it and move on. Kim says it's fine as is.

Makes me think the manufacturer may be trying to pull a fast one on John Q. Public until they're called out on it. I think they also make an 1,800 rig.

Bottom line: I know what I got and it's not the 2,000 model. I'm moving on to the next big thing. C'est la vie.

2023/01/28 16:23 · john · 0 Comments

Older entries >>

start.txt · Last modified: 2022/12/11 20:20 by

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki