Tag: HTML

bookmark_borderAuthor-it Hints, Tips, & Useful Info

Posted on

The following are not in any particular order. Some are tips gleaned from experience, some are links to the knowledge being shared by others, all have helped us get us from a standing start to a full content conversion and production delivery in under 4 months. We started with ~2450 topics of imported content, and managed to keep pace with the development team as well as cleanup and backfill the imported content. Quite a feat!

Working with Author-it

As we were converting a LOT of content from FrameMaker to Author-it, there was a LOT of cleanup required. Being able to customise the styles toolbar, adding in the most common used paragraph styles for example, was a huge bonus. We ended up creating one under the Supervisor login, and then each team member copied that to their installation.

Apparently Prompt for unsaved changes is turned off by default. We found this out the hard way, so click the big Author-it A and check in the options to turn this on.

JavaHelp Tips

JavaHelp uses the HTML templates, so if you provide customised HTML templates it will use those.

This next one might be specific to the way our development kit works.

To get context senstive help working you need to add the agreed string to the Context String field on the Help tab of the Topic Properties dialog.

We used this on some topics that will only appear in the help system, allowing us to create ‘landing pages’ which can then direct users to the most pertinent topics for the area of the product they were using when they launched the online help.

MiniTOC

These are, by default, used in Chapter templates. To get better control of the layout of these (our issues were mainly with vertical white space, or lack thereof) we decided to not have any content in a Chapter topic. That way it is only used to hold/generate the MiniTOC and the next topic holds the first block of text for the chapter.

Terminology

To make it easier to reuse topics anywhere, we switched our terminology slightly. There is no such thing as a chapter anymore, unless you have Word/PDF specific topics. We use ‘section’ instead.

Word template

The source of many a frustration, but that’s not really the fault of Author-it.

One thing I’d suggest you do first would be to figure out what macros you need and get them into the template first. Remember to configure the Publishing engine to use them as well.

We are using the following macros, all of which are available from the Author-it Yahoo Group:

  • HyperlinkedTOC – creates links from the table of contents text, rather than just the page numbers
  • RemoveCH – Removes the CH from the SuperHeading text
  • ResizePictures – makes sure images fit the column width
  • ResizeTables – make sure tables fit the column width
  • SaveAsPDF – creates a PDF of the Word document

See how to Add an Author-it AfterPublish macro to the Word template for a simple set of instructions.

Problems with numbering? Julie Goodwin, Technical Support Team Leader at Author-it, popped up in a comment last month and pointed me at this solution.

Useful links

First place to head for information is, unsurprisingly, the Author-it Knowledge Center, it’s a replication of the entire documentation set plus some very useful Tips and Tricks and Workarounds.

After that, your next step should be the Author-it Yahoo Group. It’s active and full of hugely helpful and knowledgeable people and without their help I don’t think we’d have managed to hit our project deadline.

One member of the Yahoo Group, Rhonda Bracey, has published several excellent tips on her blog. Well worth a look.

A recent addition to Author-it, one we are currently looking at, are Variants. Hamish Blunck has an excellent overview of how Variants work, and there are more goodies to be found on his website.

And last, but not least, there is an official Author-it Blog which publishes product news, tips and tricks and other random stuff on a regular basis.

bookmark_borderWhy we are moving to single source

Posted on

I’ve waffled on about single source and our plans for long enough so, as we are finally starting the process itself, I thought I’d capture some information as we go along. However, it’s probably good to set the scene, so I’ll cover that stuff first. Over time you’ll be able to see all the posts related to this work here.

Why? – why single source?

A quick summary of our current situation. We currently maintain (and add to) ~2000 pages of documentation. The same content is used for both the PDF manuals and the online help provided with the product (exactly the same, no restructuring). There are various levels of coverage (some good, some bad), we are embedded within an Agile development environment, limited publications resource. On top of that we have an aggressive release schedule and a two-tier product which includes a development kit and an application built by us using that development kit.

Whilst we have made good strides in improving how we work with the software developers – we have a technical writer embedded in each new feature team and the benefits are evident from both sides – we know we need to be focussing our efforts in the correct areas, and providing information in a structure and format that meets the needs of our audience. Luckily we have direct access to the largest section of the audience as they work for the company.

Better structured information is one of the requests, and to allow us to get the most of our current documentation we would need to reuse a lot of the content we have already, but it’s locked away in FrameMaker files, sometimes in the depths of a 100 page long chapter. What to do?

Ultimately we believe that the ability to reuse our content will make producing the content faster – the current documentation set is unwieldy and hard to search, a little digging reveals some duplication already exists – and make us much more flexible when it comes to providing useful sets of information for our audience/customer.

Eagle-eyed readers will have spotted that we already single source our documentation and online help from the same FrameMaker files, but as we don’t reconstruct the online help into something more intuitive and useful it is, essentially, an HTML rendition of the manual. Not ideal by any stretch of the imagination.

bookmark_borderRecently Read

Posted on

With the TICAD conference last week, a couple of days in my sick bed, and the imminent product release I’m working towards, I’ve not had a lot of time to post here. However, the RSS feeds keep trickling in, so here are a few items that caught my eye over the past couple of weeks.

What Beautiful HTML Code Looks Like
I’m a terrible coder. Which is just as well because I’m not a developer but as I do dabble in HTML and CSS quite frequently (hey, and PHP too), then this is a good reminder for me to develop my own best practises.

Code is Tabbed into Sections: If each section of code is tabbed in once, the structure of the code is much more understandable. Code that is all left-justified is horrific to read and understand.

Includes a neat infographic, downloadable as PDF, which is now pinned beside my desk.

Procedures: The Sacred Cow Blocking the Road
An update on a (yipes) 10 year old article. I don’t think I read it when it was first published but I have read it. Well worth another visit though.

“It takes a surprisingly short amount of time for a user to feel unstuck. When I was a usability consultant, I used to advise clients to put the critical information in the first three words of a sentence.”

IA Deliverables
From Content Surveys, to wireframes, Personas and Use Cases, a brief overview of each is followed by a sample template. Not only a useful resource but a good overview of the typical process an Information Architect will undertake, a lot of which can be adapted to more traditional product documentation.

Collaboration is not a dirty word
Collaboration on content (not documents, even if that is where the content ends up) was a key part of my presentation. It’s good to see the switch from document-centric to info-centric taking place.

I love things being this easy. I love getting (almost) zero emails with attachments. I love not having a hard drive full of Word documents.

DITA Troubleshooting specialization

The Troubleshooting specialization creates a new topic type that is well-suited for problem-solution information.

7 Ways to keep the post-conference buzz
Not long back from a conference myself, I have already done a few of these things (item 3 in particular) but some good ideas here.

Wikis for Documentation?
Steve Manning isn’t sure about using Wikis for Documentation but does think they could be a big hit in another, related area:

Most writers have to guess about their users. Few writers get the opportunity to speak directly with users. Few get any sort of feedback at all. They are left to do their best. How useful would it be to be able to post your document on a Wiki and have users be able to comment topic-by-topic? To see the questions they ask?

I totally agree. All I need to do is figure out how this works within a single source environment, and tackle a few issues around governance and change management and it could be an excellent working model.

And finally…
I’ll be updating the TechComms RSS feeds download soon, so if you think you should be on the list (or even if you aren’t sure whether you are or not) then let me know. It includes all kinds of stuff which is loosely related to Technical Communications, and I’m always on the lookout for more sources of inspiration. Leave a comment if you think of anything.

bookmark_borderSpanning the divide

Posted on

I’ve been chasing this train of thought for a while now and decided to start writing my thoughts down in the vague hope that they come together in a way that makes sense to others. It seems to make sense to me but, as yet, there are a few grey areas into which I may stumble. So, not so much a train of thought but a car crash of ideas, if you will.

Shoddy metaphors aside, the main crux of my thinking is based in my efforts to find a central point around which I can arrange my knowledge. Obviously my knowledge of some areas is greater than my knowledge of others, but part of this exercise is to start to identify the areas in which I’m lacking and so allow me to investigate them further, to feedback into my train.. no.. car… umm, driveshaft??

OK, let’s start over.

The role of a technical writer is fairly varied, and merrily traipses through several distinct fields. Most technical writers will know a little (or a lot) about many topics, how to structure information or how to create a usable index, they will be also have some knowledge or awareness of, for example, typography and readability issues, they will have some knowledge of working with graphics, and they will also gain knowledge of the various tools they use. Suffice to say that the skill set and ‘earned’ knowledge a technical writer posseses is almost endless.

And that’s all before you consider how much they know about the products that they are documenting

So from that starting point we can see that technical writers already dip their toes into various pools of expertise.

Now, let me just changes hats for a second… right. I am now a web designer.

Look at the knowledge I have attained as a technical writer, with a web designer hat on, there are a lot of parallels. Some are direct, some not so obvious but still discretely linked, after all, regardless of the medium the two disciplines share key facets of importance; content and audience. The delivery mechanism is secondary to those at all times.

Web designers also span several different fields, with some knowledge of HTML, CSS and other languages (usually text based), they too worry about layout and typography to ensure readability is maintained, they plan what type of content will be created, and understand the need to structure that information in such a way that it is explorable. The parallels are many.

So, somewhere in my head I’m wondering why the two disciplines don’t seem to be talking to one another. Is it lack of visibility? Is it just me that thinks it is this way? Are there secret meetings going on as I speak?

One of the reasons I ask is because there is a wealth of information out there that focusses on web design, even spilling over into the social/community aspects of information sharing, which the technical writing world could use and leverage. Have a look at some of the articles on A List Apart, for example. Those which aren’t specifically about code tend to talk in terms of analysis, planning and design. All things I do as part of my job as a technical writer. Boxes and Arrows takes you into Information Architecture territory, with user experience key and, for many of us who work in software development and who can influence both the UI and the Use Cases that help constitute a software application, there is a lot of useful information that we can adapt for our own use.

bookmark_borderCSS for layout

Posted on

… and why you should use it.

Separating content from structure and style is a common theory, widely accepted to those of us either using or investigating single source solutions for our documentation. The same theory has been applied to web development and offers similar benefits.

CSS-based web design developed in parallel with the growing movement towards (and promotion of) the use of standards on the web. The web standards movement was a direct response to the increasing problems faced by web designers as they struggled to keep pace with the bespoke features introduced by the browser software of the day. Advocating support for the W3 maintained standards around, initially, HTML it soon found a band of supporters who were challenging themselves, and everyone else, to stop using tables as a mechanism for controlling page layout, and instead switch to using Cascading Style Sheets (CSS).

The origin of table-based layout was, essentially, a clever hack. Early versions of HTML, and the internet browsers that people used to view web pages didn’t have any way to control the layout of a page so tables were used. Nesting tables within tables to provide discrete areas for navigation, content and so on, became the norm and some very complex examples still exist. However, as the web gained popularity and large sites started to emerge, it became apparent that table-based layout were no longer workable. They were far too hard and too time consuming to maintain, and many web developers recognised this and started searching for a solution.

Separating the content from the layout elements was an obvious step and is easily achieved using CSS. Whilst it was primarily created to allow more flexible and powerful styling, it was soon evident that, as each page element can have positioning assigned, that it could also be used as the positioning mechanism.

The basic theory of CSS-based layout is pretty simple. If you draw out the sections of your web page you’ll probably end up with several different blocks. One for the banner, one for the navigation, another for secondary navigation, one for the content, and so on. Each of those blocks can be positioned separately, or in relation to one another and as each block is uniquely identified division, then all you need to do is apply layout rules to every division to position it where you want. OK, maybe it’s a little flippant to say “all you need to do” as there is a wealth of issues to be aware of when using CSS for layout but don’t panic, there are plenty of templates to get you started, I’ve linked to some at the end of this post.

Mind you, this doesn’t really sound much different from using tables though. Right?

Wrong. The real power of using CSS for layout comes when you need to change the position or other layout characteristics of one of those divisions. For example, let’s say you have a set of navigation links in a column down the left of the page. In a table-based layout you’d have a separate table cell holding those links (which may in turn be held in a nested table to help you align them). Simple enough.

Now, you need to switch that list of links to the right of the page. In table-based layout you’d need to cut-n-paste that table cell and move it on EVERY PAGE in your website or across your help system. Do you fancy doing that for every page in a 500 page help system, because I don’t.

Using CSS for layout, you’d make a change to the stylesheet (the .CSS file) and all the pages in your website would be updated. For a large website, or for anything more than 20 or so pages, the time savings soon become evident. I’d advocate that you take this approach for smaller static websites as whilst, table-based layout is still possible, the repetition of making any minor layout change still needs to be reflected across every page.

Ultimately, using CSS for layout isn’t really about web standards, nor is it just a trend. It’s a justified and valid use of technology to allow you to work smarter, to concentrate on the content you are delivering, and not spend a disproportionate amount of time editing multiple pages of a web-based help system or website. When your boss asks you what you did last week, what would YOU rather say?

Learning CSS-based layout is not without problems, there are still browser compatibility issues to overcome, although most are now well documented and easy to grasp but I truly believe that it is worthwhile learning the basics. Of course, the internet being what it is, there are a myriad of templates available to get you started, in fact some may even provide all you need.

Related reading:
Layoutomatic – offers three simple CSS-based layouts. A good way to learn the basics.
Free CSS layouts and templates – compiled by the wonderful Smashing Magazine.
Web Standards Project – keep up to date with the latest news in web standards.
CSS Zen Garden – one structured page of content, hundreds of different CSS layouts and styles. THE example of the power of CSS-based layout.
A List Apart – an excellent online magazine for web design, chock full of good stuff.

bookmark_borderOn New

Posted on

I’d forgotten how odd it was to be the ‘new guy’, how much information we all take for granted, and how much we presume others know.

As such, I’m trying to keep a note of things that I wanted/needed to know, and also to try and embellish what exists in the hope that other new starts will benefit. One idea I’ve had, and this is certainly pertinent in a software development office, is to create a floor plan. Nothing radical I know, but by adding an extra layer of information I think it could be very handy.

We have an intranet which has a page of photos, one for each person. That’s fine if you want to email them, but a little awkward as it requires you to wander round the entire office to find “Aggie fae accounts” (names have been changed to protect the innocent). It’s doubly hard when the office is completely open plan and everyone, from M.D. to office junior, sits out in the open area. A floor plan seems kinda obvious in that situation.

However, within the development team I want to add an extra layer, a page per person, which lists their knowledge area. Basically it’s a posh way of tracking the answer to that age old question: “who do I ask about ______ ?”

Of course it needs to be a web-based system, easily updated and repeatable. I’ll rule out using a database as I don’t have the time to set something like that up, but a simple HTML based solution should be possible.

Thing is I can’t for the life of me figure out how to do it.

I don’t currently have Visio on this machine, which is probably where I would start, but even then I’m unaware of how good it is at outputting HTML. So, does anyone have any suggestions for this? Does anyone know of an easy way to create a ‘hyperlinked’ floor plan? Answers on a postcard please, and if it works out well I’ll post the solution here (with names removed, obv.!)