Wednesday, September 20, 2017

Is Anyone Writing Documentation Anymore?

So the last exercise I had done before Hurricane Irma hit was to take a computer and completely install a new operating system onto it.

I will be doing that again today, from my own instructions.

Sure, it's a bit esoteric, some people are good at reading between the lines. 

The problem with that is that you end up spinning your wheels and finding that something you assumed, you assumed wrong.

For the record, when I write documentation, I write it as I do it.  That way I know it actually works.

It may have taken 26 steps once you had all the pieces, but if you had my hardware and the right software, you'd have a nice happy laptop running Debian.  Thinkpad Laptop, X201 or fairly similar, although the version of Debian I used (Non-Free) was fairly liberal with getting what you need for many more laptops.  Evil Wifi Drivers not withstanding.

The next step was to find documentation to install a web server.

The trick with installing complex software these days is that you basically have to find the right documentation. Or to be more precise, the correct documentation.  Documentation that is complete and actually will work.

Oh and of course you personally have to read and understand what you are reading.  No distractions allowed.

However, it is rare that you will find exactly the right documentation to do what you want.  Often software is updated and that documentation you used two years ago to do that exact thing no longer works.

Highly common in the open source world, some very minor tweak will change where the files are and you are back online doing a search for what you were looking for.

In the consumer software world, you have a similar situation where the documentation was only partially updated since it was originally released.  Think Windows XP vs Windows 8.1 vs Window 10.  Things just moved around drastically within Windows itself let alone functionality.

I got "caught short" with trying to install a web server.  Did it before.  No problem.  Since it is an open source project, you get what you pay for sometimes.  Following the wrong guide I got the entire web server working.  I just don't have any passwords for anything.

As they say on a football field:  Drop Back 5 and Kick.

That would be American Football.  I never played Soccer, at least not for any length of time.   All that running around annoyed me.

So at some point I'll re-attempt that mess.  FInd another tutorial that promises to install the LAMP stack and write down what I did.

Or I will find that one bug and fix it all.  My choice, after all.  

That is why I keep this blog.  Many times I need to do something more than once.   Create a Linux Web Server, save it off, then reproduce the results on a different computer a year later.

So when I post a long diatribe on how to do this and the other thing, I'm doing it for Future Me.  So I don't end up banging my head on a wall.

Like Today.  I got it wrong.  Happens.  Time to start over.

For now, I'll just go look for the football.  Maybe the dog will chase it around the yard.  Blow off some steam.  Finish my Spanish for the day. 

Try, Try again.

No comments:

Post a Comment