Writing Documentation for End Users with Search and Index


#1

Hi there!
I am being asked to write end user documentation for the users in my company. I have the technical writing down, but is there software or any other method that I could use that would index my documents and make them searchable?

Thanks!


#2

What software are you using for documentation?


#3

Hi!

Thanks for responding. I’m just using Word, but am open to suggestions :slight_smile:


#4

IMHO, MS Word has a very limited set of options for making the docs searchable.
If your company is open to move to some other tool then theres plethora of tools available in the market

Thanks,
Mandar


#5

FrameMaker used to be a sort of standard for technical writing, and it does make ToC and Index generation pretty easy. You can output to many different formats. Not sure what you mean by searchable though. Are you generating PDFs? Sending the Word doc out as is? Do you print it at all? Publish to HTML?


#6

It’s actually a pretty simple project. I want to put it on a shared drive for all (~100 people) to access at any given time. The content is basic: how to setup remote access, signatures for email, how to configure devices etc.

Searchable…just meaning if someone is searching for a particular phrase, word, the document(s) with the phrase, or word will come up in the Search results. Windows doesn’t do a great job at searching :slight_frown:

So the project will be online, whether people choose to print it out is up to them.

Thanks for your response.


#7

There are always two types of search: search from within the document, and honestly, any PDF provides the best searchability for that. But if people are searching from google, then you want to publish in HTML and use the rules of SEO.

You don’t really need an index if you save it as PDF, as the search in PDFs is great and in practice, we found most people prefer to use it to any other search in any other doc format. But it’s not good for internet searches.


#8

Perfect. I’ll convert my docs to pdf. I much prefer doing that (convert to pdf) anyway with my documentation.

Again, that you for your response, and your advice is most appreciated :smile:


#9

If you are providing actual user docs, however, remember that users have to know what the word is that they are searching for in order to find it. Or you have to create real SEO and mappings. Just assuming that users know that (for example) you are using “editing a password” and they want “changing a password” means there could be failures. An actual index (which is easy to provide in Word using XE fields) allows you to create synonyms and cross refs to all terms. And added bonus, if you are creating user docs for products, you can also index terms your competitors use.

Just my two cents. For a PDF that could be printed, I still firmly believe you should include a real index. If your doc is intended to be served as HTML, then use search only. But don’t provide search only for a PDF doc. Search is not a replacement for an index in every case.

…sue