3

I'm the only technical writer in my company with 2 years of experience. I have been assigned with a task of creating a functional document for a web-based (FMCG) product which has been around a long time at least 7 years with no proper documentation. This is a challenging task for me as I have been only creating GUI based user manuals (with not much technical information). I really want to use this opportunity to create a complete document that is really helpful for the team. The document would only serve as an internal reference document for the product team. How should I gather information and structure the document?

2

In many ways you approach this the same way you would approach any other new project:

  • Review any available high-level descriptions (like functional specifications) and user stories: what is this thing and how are people meant to use it?

  • Identify your key contact (if you don't have one, ask your manager how to get one) and schedule an overview discussion. This is a "give Ashvita the lay of the land" discussion, not a "tell Ashvita all the gory details" discussion.

  • Sit down with your contact and the software and get some hands-on exposure. Don't try to cover everything; ask the expert to point out the most important and most common paths through the tool.

  • Start to compile questions (which will surely arise as you work with the product).

Now in addition, this product has been around for years and people have been using it, even without documentation. Either everything is completely obvious (in which case they probably wouldn't have asked you to document it) or there's a lot of "oral tradition", maybe even informal notes, wiki pages, and so on. You want to tap into that.

You should ask your key contact for pointers to any such artifacts and, also, who the main in-house users are. (They might be your own QA department, if you don't have people in-house relying on the product.) Gather the information you can.

That's all about the research part. To organize everything you need to have some sense of who your users are and how they'll use the product. The same techniques that you use for other technical-writing tasks apply here. A full treatment of user-needs analysis and organizing content would be too much for one Stack Exchange answer, but feel free to ask narrower followup questions.

1

I believe that you want to use (structured) FrameMaker, perhaps integrated with RoboHelp if you need a variety of output types. Both products are part of Adobe's Tech Comm Suite product (and you actually need the suite for FM-to-RH integration).

There is a ton of material about how to use FrameMaker. To help you, here's the link for a long list of previously recorded online seminars for FrameMaker (Adobe login required).

Specific concepts that you're interested in are:

-structured FrameMaker (as opposed to unstructured)

-DITA strategies

-ExtendScript

-XSLT and XPath

-Localization strategies (if you're thinking ahead)

There's a lot there, but that's what you want if you're thinking long term. Plus, you'll learn transferable skills that will serve you well in future.

  • 1
    Isn't choosing a tool or a DTD premature? It looks to me like the question is more about learning an unfamiliar domain and organizing that. On the other hand, the OP did tag it tools; hmm... – Monica Cellio Apr 29 '15 at 21:16
  • Thanks for the detailed answer. This is what I'm looking for. And yes, the question is about learning the unfamiliar domain and organizing the content. As for the tools part, I use MS Word and Robohelp. I ll have to continue to use MS Word/RH for documenting. The document would serve as an internal functional document for the product team and not for the end users. – Ashvita Apr 30 '15 at 5:04
  • @Ashvita that's important information; internal documentation is different from something you publish broadly. Could you edit that into your question? Thanks. – Monica Cellio Apr 30 '15 at 12:30

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.