GeekNights 090601 - Documentation Systems

Apreche

Tonight on GeekNights we discuss systems for handling business documentation. In the news, Palm Pre is coming really soon, and so is Google Wave.

Scott's Thing - Dnsmasq
Rym's Thing - The Wrong Door

Ishmael Dummy

Years ago I administered several Zope/Plone websites, where non-tech savvy users used Structured Text to upload documents. On the whole it worked well because they were discussing the documents via email, and so got used to expressing emphasized text in *asterixes*, bullet point lists with dashes etc. I wouldn't want to try anything more complicated than that.

Apreche

Years ago I administered several Zope/Plone websites, where non-tech savvy users usedStructured Textto upload documents. On the whole it worked well because they were discussing the documents via email, and so got used to expressing emphasized text in *asterixes*, bullet point lists with dashes etc. I wouldn't want to try anything more complicated than that.

You were very lucky to have such smart users. Markdown, which we discussed in the show, is similar to the structured text. There are other alternatives as well, such as Textile. If you can get users to learn it, great. If not, good luck.

Luke Burrage

In the news,Palm Preis coming really soon, and so isGoogle Wave.

Scott's Thing -Dnsmasq
Rym's Thing -The Wrong Door

Some comments (after listening to half the show):
The Wrong Door = funny, but not amazingly so. Funnier than Dnsmasq.

I'm REALLY excited about Google Wave. I watched the entire video on Friday, and had a really fun discussion that night with a friend about it. He's very anti-Google, mainly because his email is read by Gmail when he sends it from a non-Gmail account, and he might not even know it is coming to a Gmail account that can be read. He says it's his data. I say if it's in my inbox, it's my data, and I'm letting Gmail read it because that's the price I pay for good spam filtering/the best email threading/etc. Anyway, we were both hyped about this because it's an open platform, and info doesn't have to go via Google. I've already come up with some ideas for "robots" or "widgets" that will be really good fun and/or useful.

Twit was great this weekend. Gdgt isn't keeping my interest, but they use chapters for easy skipping of non-relevant topics.

Luke Burrage

I've seen this before, but someone in a chatroom just linked to it, and I'd also just finished the whole Monday episode. It seems relevant: How To Write Unmaintainable Code
Ensure a job for life ;-)

Omnutia

Scott's Thing -Dnsmasq

This is included with the Tomato firmware for WRT54G. I use it to give names to all the computers on my network.

VinceA

DNSMasq is also included with DD-WRT. Using it on my home network.

gomidog

Man, I could so relate about people using a bunch of word files on a D drive somewhere on the network as documentation. For a long time, a lot of the shared documents were Powerpoint files. It was not good.

HeavyCruiserLost

I've had similar problems with all this documentation mumbo-jumbo. I was wondering if you guys have found a elegant solution for keeping track of all the usernames and passwords that come along with the technical documentation?

Apreche

I've had similar problems with all this documentation mumbo-jumbo. I was wondering if you guys have found a elegant solution for keeping track of all the usernames and passwords that come along with the technical documentation?

Uh, usernames and passwords should be stored in your brain.

YoshoKatana

I'm so excited about Wave. Hopefully I can write something soon that will integrate it with bugzilla and our ticketing system. I think it could change the face of customer support.

HeavyCruiserLost

I've had similar problems with all this documentation mumbo-jumbo. I was wondering if you guys have found a elegant solution for keeping track of all the usernames and passwords that come along with the technical documentation?

Uh, usernames and passwords should be stored in your brain.

Agreed. But this still doesn't solve the problem of having a series of system passwords that your boss and various other coworkers need to have on record. You can always just call them on the phone or mail them a letter, but this is a seriously low tech way of passing around this information.

Rym

But this still doesn't solve the problem of having a series of system passwords that your boss and various other coworkers need to have on record.

They need to know them. No organization should have records of passwords for anything: multiple users should have their own password access to the same data, and need-to-know employees should either have the passwords in their heads or have alternative access to the data.

If there are somehow universal passwords that must be recorded, they should be stored in an encrypted volume (replicated to a DR site) that only the board of directors members have their own (in their heads) passwords to.

Generally, any time you find yourself storing a password anywhere in any form for anyone's reference other than yourself, you are solving your problem the wrong way.

Apreche

Agreed. But this still doesn't solve the problem of having a series of system passwords that your boss and various other coworkers need to have on record. You can always just call them on the phone or mail them a letter, but this is a seriously low tech way of passing around this information.

You shouldn't have a system of passwords. No password should be shared, ever under any circumstance.

For example, let's say you have a Linux server and three different IT guys need root access. Do not under any circumstance decide on a root password, and all share it. Instead, create three separate accounts for the three separate users, and use sudo. If it's an old UNIX system without sudo, create three separate accounts with uid=0.

Never share a user account or password, ever.

EVER.

Nine Boomer

Agreed. But this still doesn't solve the problem of having a series of system passwords that your boss and various other coworkers need to have on record. You can always just call them on the phone or mail them a letter, but this is a seriously low tech way of passing around this information.

You shouldn't have a system of passwords. No password should be shared, ever under any circumstance.

For example, let's say you have a Linux server and three different IT guys need root access. Do not under any circumstance decide on a root password, and all share it. Instead, create three separate accounts for the three separate users, and use sudo. If it's an old UNIX system without sudo, create three separate accounts with uid=0.

Never share a user account or password, ever.

EVER.

My school has upwards of thousands of students, and everyone has their own username and password. All of these passwords are saved and fully accessible to those with the clearance necessary. Of those people, one is my teacher for a technology oriented class. He has access to the networked private folders of everyone in the school, as well as access to the passwords. Once, he accidentally turned on the projector with the passwords open on his laptop and displayed it to the whole class for a second or two, sadly while I was looking away.

Also, I've seen students share their username and passwords casually between themselves.

Another problem is that the passwords are all composed of two words with a symbol between them. It seems easy to crack with a dictionary attack. At least the account gets locked after a certain amount of tries.

Rym

All of these passwords are saved and fully accessible to those with the clearance necessary.

No one, not even system administrators with root access, should EVER be able to see another user's password under any circumstances. They, at most, should be able to RESET these passwords (without ever knowing what they were originally). Anything less than this is bald incompetence.

He has access to the networked private folders of everyone in the school, as well as access to the passwords.

Whoever set that up should be fired. Passwords should be encrypted. No one should be able to see them. Ever. Again, bald incompetence.

Once, he accidentally turned on the projector with the passwords open on his laptop and displayed it to the whole class for a second or two

Bald incompetence.

I've seen students share their username and passwords casually between themselves.

Always a bad idea.

Another problem is that the passwords are all composed of two words with a symbol between them.

Again, bald incompetence. They should be forced to change these random passwords at first login.

HeavyCruiserLost

In an environment where one can create, remove, and control users, employing the principles you guys are talking about is what one should always do. There is however are lot of every day technologies and situations where one has no ability to create separate users for each of the people that might need access. Things like lower-end routing equipment used by small businesses or a shitty webhosting company that doesn't support adjunct users your boss insists on using. More and more companies are deploying IT through 3rd parties and it isn't uncommon to do work for an employer and only communicate with them electronically.

I know there are is a right way to do things, but day to day you end up spending you time solving the problems you are getting paid to fix and not to critique/fix a half-baked IT setup.

jefferson

Rym, have you ever tried Confluence? Link

It allows users to edit wiki pages in Word or other office products, has workspaces that you can allow and deny access to for different users, and even can even make links to other pages by brining up a search box and finding the page you want to link to. For user managment it can connect to LDAP.

Rym

Rym, have you ever tried Confluence

Have you? Or did you just find that with Google?

It's "enterprise" software, and it costs thousands of dollars. Furthermore, while I haven't tried Confluence itself, I did demo their other products, and was fantastically unimpressed. I highly doubt that Confluence is worthwhile.

Rym

In an environment where one can create, remove, and control users, employing the principles you guys are talking about is what one should always do. There is however are lot of every day technologies and situations where one has no ability to create separate users for each of the people that might need access.

In those special, specific cases, you do exactly as I said. You make an encrypted file that only the board of directors can access, and each need-to-know user memorizes the passwords.

I know there are is a right way to do things, but day to day you end up spending you time solving the problems you are getting paid to fix and not to critique/fix a half-baked IT setup.

Well, I'm paid specifically to ensure that every problem is solved the right way, and I'm expected to critique/replace half-baked solutions. That's what IT is all about. Any time a business dictates bad IT, there is either incompetent direction, an incompetent IT staff, or a concious business decision to use a high-risk, low-cost solution.

If IT is forced to do something the wrong way by management, they are obligated to raise their concerns and, if all else fails, provide a record of their objection. Bad solutions should either not be enacted, or enacted with documentation of the risks and money savings.

That said, most of the time, when someone does something the wrong way in IT, it is due simply to their not knowing how to do it the proper way.

gomidog

That said, most of the time, when someone does something the wrong way in IT, it is due simply to their not knowing how to do it the proper way.

My office's IT guy, Gah! Also, he was a complete skinflint and bought all cheap and unreliable hardware.

...

My office's IT guy, Gah!

Stop reading that line, less we end up with you 'Gah!'ing constantly.

gomidog

Ironically, the dual post was the fault of slow wireless and the page not loading properly. It's the crap wireless router. Guess who bought it? Gah!

sK0pe

This episode pertained to me more than usual as I'm writing a number of protocols for nurses to learn from but unfortunately my boss wants everything in Word format in a number of separate documents in a folder on a network drive.

It's fairly small information wise but is highly inefficient especially when I worked out the nurses were having difficulty finding the freaking files to read!
I was thinking of making a basic HTML setup but then other Vets (if protocols need to be changed) at my practice can't edit HTML - they struggle with word processing efficiently so this is very frustrating.

I'm at my wits end and I definitely know that that Wikis are going over people's head. I don't even know how to program anything beyond Wikis and markup.
Tech / IT / CS should be a high school requirement.

YoshoKatana

I find it inexcusable if intelligent, sapient adults cannot learn basic mediawiki markup in less than an hour. It's not rocket science, people.

Apreche

I find it inexcusable if intelligent, sapient adults cannot learn basic mediawiki markup in less than an hour. It's not rocket science, people.

Then you find the overwhelming majority of the world population inexcusable.

Remember, it's not just a matter of whether they are mentally able to learn it. In fact, most sapient adults are probably capable of learning a simple markup language in less than an hour. The problem is that almost none are both willing and motivated to do so.

YoshoKatana

Well, in sK0pe's example, these nurses are professionals who have a defined need; a documentation system. Something like a wiki would work perfectly for what they want to do (as far as I know), and yet they try to improvise solutions based on their (flawed) IT knowledge. I think they, if anyone, should be willing and motivated to learn something so simple. Hell, there are WYSIWYG wiki editors out there. If they can't use a very simple editor like that, I question their ability to function in today's world.

Apreche

Hell, there are WYSIWYG wiki editors out there.

They're all absolute shit.

If they can't use a very simple editor like that, I question their ability to function in today's world.

That's just it. The vast majority of people are living in the past. Technology is advancing at a very rapid pace, but only a very small number of people are actually willing and able to keep pace.

YoshoKatana

That's just it. The vast majority of people are living in the past. Technology is advancing at a very rapid pace, but only a very small number of people are actually willing and able to keep pace.

True. Too true. I love working at a web startup.

cosmicenema

We're working on a big documentation project for our new admin system right now and let me tell you, as a project manager, it's very difficult to get the budget, time, and resources for your 10% documentation approved in a project but I agree it's generally worth the effort.

I wish your answer was something other than 'the solution doesn't exist yet'. I've set up wikis at two different employers and they don't seem to work. We're trying to use sharepoint now but there's still a lot of issues there. Rational Pro and HP Quality center are OK for project documentation but not for business usage. We rely a lot on our HR and Training departments to translate into Word for the actual users. I tried to get us using Google Docs for a while but no such luck. It's a pervasive enough problem we'll need a solution eventually.

I'm enjoying the business process episodes so thanks!

sK0pe

Update, I pitched a Wiki to the staff and the partners at the practice who were all for it till I started editing and then asked to see if they thought the other vets could handle it, they didn't think so, I would probably agree except for one of my co-workers whose main PC is an ASUS EEE PC running Linux (and this guy is 60+ years old).
I think it would be possible people just become frustrated and blame computers or just turn around and say "I have a Mac", which has nothing at all to do with the markup code!
What doesn't help is that all the Veterinary programs on the market or custom programmed programs are very unintuitive and poorly written, requiring excessive demands of a PC terminal to run a very simple program.