How to create a functional document for in-house reference?
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?
This post was sourced from https://writers.stackexchange.com/q/17005. It is licensed under CC BY-SA 3.0.
2 answers
You are accessing this answer with a direct link, so it's being shown above all other answers regardless of its score. You can return to the normal view.
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.
This post was sourced from https://writers.stackexchange.com/a/17009. It is licensed under CC BY-SA 3.0.
0 comment threads
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.
0 comment threads
0 comment threads