Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

How to create a functional document for in-house reference?

+0
−0

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?

History
Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

This post was sourced from https://writers.stackexchange.com/q/17005. It is licensed under CC BY-SA 3.0.

0 comment threads

2 answers

+1
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

This post was sourced from https://writers.stackexchange.com/a/17009. It is licensed under CC BY-SA 3.0.

0 comment threads

+0
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

Sign up to answer this question »