Warning: "continue" targeting switch is equivalent to "break". Did you mean to use "continue 2"? in /homepages/30/d88601657/htdocs/techright/blog/wp-content/plugins/social-networks-auto-poster-facebook-twitter-g/inc/nxs_functions_engine.php on line 169

Warning: "continue" targeting switch is equivalent to "break". Did you mean to use "continue 2"? in /homepages/30/d88601657/htdocs/techright/blog/wp-content/plugins/social-networks-auto-poster-facebook-twitter-g/inc/nxs_functions_engine.php on line 176
Technology | Tech-Right Documentation Blog

Category: Technology

My Adventures in DITA, part 3

No Comments on My Adventures in DITA, part 3

January 21, 2014 at 12:00 pmCategory:Technology

Long time since the last update. Life got in the way. But hey, I promise to refund all money you paid me personally for reading my blog.

I sort of forgot to explain why would people care about another unfamiliar acronym in the tech world. So let me do that now, before carrying on. After all, the business side has to be convinced that a technology is worthwhile before they agree to spend money on it, right?

DITA offers a lot of benefits. I will just highlight the ones that are attractive to me.

  • Control of layout and format.
    If you have a pubs department with a bunch of FrameMaker or Word templates, that is great. But unless you have some really esoteric things going on with these templates, individual content creators can always decide that something in the template looks stupid, and that you should be able to list seventeen tasks in a row with a mix of bullets and numbers in the task items, and you don’t need to explain why you are doing each task, because it is so OBVIOUS.
    DITA, based on XML, enforces structured authoring strongly. You can’t get usable output out of it unless you conform to the template set up by your template controller. You can’t not describe what a task does. You can’t put pictures on the title page. And so on. And so on.
  • Single sourcing.
    Write once, reuse in multiple places. Your text can be marked up to only be published to a certain stream (PDF, online), or to only a certain business purpose (marketing versus help manual overview). This saves a lot of time when you are updating existing text. There aren’t five or six documents floating around out there, there are one or (at most) two.

There are other ways to get this. FrameMaker has its structured authoring environment, and some limited DITA support. Other tools also allow you to edit and create single source material (e.g. AuthorIT, Madcap Flare, RoboHelp). But these all cost money.

DITA, at least to install to play around with, is very low cost. Download it. Download and install the JDK. Start playing around.

At the enterprise level, of course, nothing is free, not even open source software. The question of whether implementing DITA versus buying something off the shelf is not something I am going to directly cover here, but I will infer it as I go through the mechanics of getting DITA running.

My Adventures in DITA, part 2

No Comments on My Adventures in DITA, part 2

October 27, 2013 at 11:19 amCategory:Technology | Writing

With the DITA Open Source working at the level I need it, for now, I need to go in and figure out how DITA is structured at a high level.

(I say “for now” because experience has taught me that base configurations never do what you want them to do when you get some experience in the system under examination.)

People will tell you that DITA is just XML, so it’s simple.

<?xml version="1.0" encoding="UTF-8" ?>

<title text="Hi there this is XML!/>

<para>Golly, XML is easy!</para>

That is easy XML. DITA is a wee bit more complex than that, as it is a full-fledged publishing system. Incoporating multiple XML files, multiple transform types, topic maps, other maps, this and that…honestly, I know very little about it, beyond the fact that it’s not easy.

Even if you buy some kind of tool that is supposed to make DITA authoring simple, the fact is that someone in a place using that tool will, from the start, need to understand the possible ways you can build and extend a DITA architecture.

So, as I go through it myself, I will blog my adventures in DITA.

My Adventures in DITA, part 1

1 Comment on My Adventures in DITA, part 1

October 24, 2013 at 1:08 pmCategory:Technology | Writing

So after a presentation by Tim Grantham this week on his new InPrint solution, I thought it was time to look at DITA again.

Since my budget for new software comes solely from sweat equity, the Open Toolkit was the only choice. I will worry about an editor later.

The first test of DITA Open Toolkit is whether you can find the documentation. I didn’t find this process intuitive or helped by the README, but by clicking enough I found the XHTML help file.

The second test of DITA Open Toolkit is how well you know Java. Upon trying to build the demo output, I got a cryptic error message in the DOS shell. Upon thinking, I realised that of course I need a JDK.

After trying again to build the output, I realised I needed to edit the provided DOS batch file to tell it where to find the JDK bin directory.

This accomplished, the output built. Even though I added the JDK CLASSPATH to the startup batch file, Ant is still looking in my JRE for tools.jar.

So, not perfect, not intuitive or well documented, but it works. Now to find a free editor and get to work learning  DITA authoring.

The LinkedIn Announcement

No Comments on The LinkedIn Announcement

June 2, 2011 at 9:44 amCategory:Social Media | Technology

Not a “surprise” announcement, by any means. Ever since they’ve been around, they have pushed us to get our profile up to 100% completion. This included, of course, getting recommendations from colleagues.

And then, their IPO on May 19th, 2011. All kinds of cash flow. So now, they are formalizing their business model in an obvious vs. their previous badly hidden way.

This includes a button which basically lets job applicants send employers or recruiters their profile information, as I understand it. So, this couples Linked In even more tightly with the job application process. Their little button can expand across the web like the, well, “Like” button.

So what does this mean to the job application process? It expands the influence, or tries to expand the influence, of Linked In so that when you think “I want to apply for a job,” you automatically think “Cripes, where is the Linked In Apply for this position button?!?!”

Just like Facebook is trying to make you think, “I need to contact Jill Jetson, so I’d better log on to Facebook and leave her a message.” In the case of Facebook, you could use e-mail, but it’s a bit more inconvenient, and in the case of Linked In, you could go to a job board and try to remember your password and upload your resume again, but it’s a bit more inconvenient.

In this Web 2.0 World (which sounds better than Multitasking Hell World), don’t underestimate how much people appreciate a little less inconvenience.

A World Full of Apple

No Comments on A World Full of Apple

March 25, 2011 at 7:56 pmCategory:Technology

We now enter the mobile shakedown wars. Once-mighty RIM, now dancing around to keep and regain market share. Microsoft, late to the game with a strong mobile product. HP, with Palm’s WebOS and a dream.

And, of course, the two behemoths, Apple and Google. Apple with their closed ecosystem, and Google with their fake open Android ecosystem. Can anyone topple these two Titans?

Maybe Amazon, with the rumours of their own tablet? The thing that pushes mobile device sales is content to put on said devices, and Amazon is nothing if not filled with content. I read this little rumour on another site today, and frankly, it makes a lot of sense.

Whoever can deliver the killer content will win. So why not Sony? Why not a Sony tablet? They have a catalogue full of things people want to see and hear.

Ok, but…the one who can deliver the best streaming content will win.

At The Four Seasons

No Comments on At The Four Seasons

January 31, 2011 at 7:59 pmCategory:Technology

I haven’t had overpriced hotel food for a while. And I needed to spend some time before the TSPUG presentations began.

SharePoint is a fun beast. As a user, I see the surface of what it has to offer. Then I come to these Toronto SharePoint User Group meetings to get a handle on some of the tech behind it.

The highpoint of the evening is a set of ten minute presentations. All these SharePoint experts getting up and sharing their knowledge through demos and talks.

A good time. And as for the cafe at the Four Seasons, the dungeness crab salad is recommended, the sweet potato gnocchi not so much.

The RSS and the Browser

No Comments on The RSS and the Browser

January 2, 2011 at 9:22 pmCategory:Technology

So, Mozilla is going to yank out the RSS button from the next version of Firefox. Their reason: lack of usage.

If you’ve ever worked in coding, you know that ripping a piece of code out of something is almost as much a pain as adding new code. There is testing involved in both. Sometimes doing regression testing is more painful than testing new functionality, although in the case of an RSS button, it seems like mostly standalone functionality.

Still, ripping code out takes work. Even if users aren’t using it that much, why bother? I can think of two reasons:

  • Mozilla wants more screen real estate for some even better piece of shiny stuff that will make RSS users not lament the loss of the RSS button
  • Business analysis at higher levels has decided that anonymous browsing of peoples’ Web sites is not desirable. All input should be first filtered through a corporate aggregator, like Facebook, or Twitter. This lets the corporation track what interests users, and serve up ads and other revenue attraction interfaces designed  to pull money out of people based on their aggregated browsing habits.

I echo the last point based on what I read here. The point made there is not that the technology behind RSS is bad, but that the user interface to access RSS is barely implemented on most websites. You get a cryptic little button which looks like the end result of a snail race, and then the average end user winds up not clicking on it. The fact that it’s a crappy implementation winds up being interpreted as “It’s not a function people need”.

Basically, it’s like having a little hole in the wall restaurant that serves delicious food cheaply and quickly, but the owners never spent any money on the front of the shop, so people walk by the concrete facade with the sign saying “RFF” (Really Fine Food) because it looks ugly and they can’t be bothered to figure out what it means if the business owner didn’t care enough to put an effort into it..

I mean, this is basic usability. This is like, first year usability. Don’t make your users struggle excessively  to figure out what something does. And don’t make it difficult for them to do a task when they do figure out how to start it up.

Dave Winer was talking about forking a branch from the Mozilla code and making a version that implements RSS properly. Heck, I’d install that. But at least Mozilla had an RSS button. Goggle Chrome doesn’t support it. I’ve never seen such a thing in any version of Internet Explorer either.

RSS is an invaluable service, and it’s not going away, because it powers too much stuff. But here’s hoping some bright people get to work on something that seems to have been ignored, making it accessible to the average non-technical user.

SVN Made Simple

No Comments on SVN Made Simple

December 27, 2010 at 12:45 pmCategory:Technology

I use Subversion for source control at home. No real reason, except that I started with it many years ago and it is fairly popular.

I use git in other places, and git seems pretty good too. git is more lightweight, but I do like the TortoiseSVN Windows plugin for graphical goodness.

Anyway, I always get a bit confused when I first set up an SVN repository. Until I came across this. It’s a bit dated, but still a good summary.

The Tech Apple of Discord

No Comments on The Tech Apple of Discord

November 17, 2010 at 10:16 pmCategory:Technology

The original Golden Apple of Discord is, of course, the one that started the Trojan War. “To the fairest.” Well, which one is the fairest? Let’s start a war because that guy picked her as the fairest and get Helen back as our excuse for starting the whole mess.

Of course, in technology, no one cares who the fairest is. Booth babes are outlawed, and most geeks are male with various levels of hygeine.

But, toss in a golden apple marked “To the smartest”, and oh boy! Watch the USB drives fly! Because intellect is a mark of status. Because smart people are at the top of the meritocracy in the tech world because, of course, you need brains to be good in tech.

Well, yeah. You need to be able to at least grasp some elementary  technical concepts, depending in what part of IT you have elected to hang your hat. But what is happening with the world? Social media with the many who don’t care about whether you have a 64-bit architecture or not, and any moron knows Ubuntu Linux is weak compared to the flexible power of Gentoo, especially with the custom kernel you built and compiled for YOUR processor, and…

They don’t care. They just want to get their widget that they paid money for, and they don’t want any techno wafflegab.

But, if someone who has NO technical understanding tries to explain the problem to them, what happens? “Yes, sir, there is a problem. We are working to resolve it. Our technicians are working hard on your issue. It is an issue on our servers. I don’t know how serious it is, but rest assured, we are working hard to resolve it.”

What if you went to a typical high tech company and tossed in a golden apple inscribed “To the most integrated”?

My guess? A lot of head scratching and then coffee break. But really. Shouldn’t that be the apple you should really be fighting over?

The Hero and The Community

No Comments on The Hero and The Community

November 2, 2010 at 10:44 pmCategory:Social Media | Technology

There is…wait. Let’s talk about YOU first.

Maybe you’re a teenager. Maybe you’re a geek professional working a good job. But it’s you, right? You are the hero of your everyday life, you make it happen, you’re special.

So, things you do are special. How you dress, what you eat, where you go. Where you go. If only there was some way to track that…

But wait, there is! All these great companies like Foursquare and Gowalla are giving you the ability to check in to places and let people know where you are. You can earn badges, and with Foursquare, you can even become the mayor. The mayor! There’s a nice title for a person like you. President or King or Empress just sounds too much, too ridiculous, but Mayor…there’s a title that’s just right for someone of your eminence. Mayors are important and get things done, but they are approachable, and that’s what you are, right? Approachable.

So check in! Your friends can find you and they can check in, too! You can all check in and tell the world, “Here I am, this is me, this is what I do, this is my life in exquisite personal detail!”

What about the community? You’re in it, right? You’re enriching it by your presence, and everyone should know that!

Wait, I forgot, I was going to talk about something else at the start. But here it is.

There’s a different kind of checking in offered by www.blockchalk.com. It is different in that it’s totally anonymous,m and your “chalks” are sorted by your location. which defaults to your neighbourhood. Not Frou-Frou Cafe, just that you’re in West New Old Portobello.

And your name, or ID, doesn’t show up unless you type it in. So you are sort of coerced to enter something about your neighbourhood, the area where you are existing in at the time. A sort of broader sense of where you are.

You can also categorize your “chalks” around things like Nice, Lame, Crime, or just Ask something of other people. About the neighbourhood in general, or even about Cafe Frou Frou. But it’s not immediately about you, this great person, being the centre of attention, with your ID and your badges and your mayorship. It’s implicitly biased towards making you anonymous and talking about your surroundings and how other people might interact with these same surroundings.

Maybe it’s not surprising that the Hey look at me I’m over here apps have dominated the marketplace, and Block Chalk is sort of over there in the corner. Will it get some market traction? I don’t know. But I wish it did and let us remind each other that life isn’t always about Hey me I’m here me.