Student tech writer new to MadCap-New project best practices

[seasonedrookie]

Greetings,

I'd like to introduce myself to everyone here at the MadCap Software Forums. My name is Ryan and I'm a graduate student in technical and professional writing. I am also the proud new owner of the MadPak suite.

A little about me...I've completed two internships in the technical writing field, learning InDesign, Frame, and Arbortext along the way. I've completed all of my coursework for my Master's degree and have begun working on my thesis. I was recently hired on by a company as a contract technical writer to write the standard operating procedures for some of their field equipment.

I've read Scott DeLoach's book, "MadCap Flare Certified Test Review + Developer's Guide". I've got Lorraine Kupka's, "Five Steps to MadCap Flare" coming in the mail soon.

What I'd like to get some advice on are the best practices for beginning a new project from scratch in Flare. I've got some documentation from the company in Word, but rather than import it, I'm planning on starting with a blank Flare document.

What needs to be set up first?

Should I create a master stylesheet first?

Should I create a stylesheet first?

Should I create a master page first?

Should I create a template first?

I'm just trying to figure out a standard order of doing things. If anyone can tell me what to do second, third, fourth, fifth, etc. that would be great. If you can point me to an archived thread with this sort of information that would be appreciated as well.

I also wondered if there is a good engineering template or stylesheet available that I could download and have everything set up for me so I could just get started on the writing work.

Thank you all for any help you can provide. I'm happy to be a part of the forums and I'm excited to learn Flare.

Kind Regards,

Ryan S.

[lacastle]

Have you searched the forums for best practices? I know there are a lot of topics written about this, as well as Flare manuals linked from the MadCap help.

http://forums.madcapsoftware.com/viewto ... =4&t=13122 - one example of getting started tips
http://webhelp.madcapsoftware.com/flare7/Default.htm - pdfs at the bottom
http://forums.madcapsoftware.com/viewto ... 114#p45836 - search the forums using google
https://www.madcapsoftware.com/bugs/submit.aspx - submit a feature request or bug if you don't find in flare what you expect

welcome to the forums!

[Nita Beck]

Hi Ryan,

Congrats on your graduate work and on already landing a job (albeit contract) in your chosen profession. You're on your way!

You'll find that "Five Steps to MadCap Flare" will answer many of your questions. Lorraine's book is loaded with best practices, and the book is actually intended for users exactly in your position: new to Flare, needing to create a project from scratch, and wondering what to do first, second, next, last.

(Full disclosure: I know Lorraine personally but have no financial stake in her book.)

[seasonedrookie]

Thank you for your responses. I encourage others to throw in their .02 cents as well.

Yes, Ms. Kupka actually emailed me personally after I submitted a question to the publisher website. I thought that was pretty cool. The DeLoach book does a great job of explaining what everything does, now I just need to put it into practice. Happy to hear that Lorraine's book will bring me the rest of the way. Seems as though my decision to buy both books was a good one. Now if I could only afford MadCamp.

I do still wonder if there are downloadable stylesheets or templates available on the web. My first internship was in an engineering environment and they had a nice template in place for their manuals. I'd like to have access to something that would give my current work the feel of an engineering manual. Undoubtedly, it would be a good learning experience for me to build everything on my own, I just don't know if I have as much confidence in my styling abilities as those who've been at it for years.

Thanks again. Keep posting, I need all the help I can get.

[lacastle]

Undoubtedly, it would be a good learning experience for me to build everything on my own

This is very true. You can look at the standard styles that come in flare (all the css settings before you make any changes), but learning CSS is arguably one of the best things you can do to be good at Flare.

[Nita Beck]

I also strongly advocate for getting connected with other Flare users in your geographic community. Where I live, I reached out to other Flare users through my local chapter of the Society for Technical Communication. We ended up forming a user group back in 2009 that meets monthly (next meeting in two days! Can't wait!). The user group has been a wonderful place for Flare users -- new and expert -- to share ideas. I've been using Flare since it first came out in 2006, but I continue to learn new and exciting techniques with each user group meeting I attend.

There's nothing magical about forming a user group, by the way. Just find some cohorts, choose a nice cafe to meeting in, and start talking! (It will take some care and feeding, though, to keep it going.)

[crdmerge]

I agree with Laura about getting proficient in CSS. Again, you'd probably want a good book for that, but you can start by bookmarking http://www.w3schools.com/css/default.asp for the CSS Tutorial on the w3schools web site. And http://www.w3schools.com/html/default.asp for the HTML Tutorial.


Good luck,
Leon

[seasonedrookie]

I appreciate the feedback, but I'm running into a problem. I need to get started now and I fear the learning curve will be too slow to keep my managers happy. They asked about Flare and why it's better than Word. I tried explaining, but I'm having trouble putting it into words and I have no completed work in Flare to back up my reasoning. I'm about to be stuck making this manual in Word.

Are there templates that I could download to get this project off the ground? I don't know that I have time to design everything myself before management begins to question my work.

[wclass]

What are you looking for in a template? You said earlier you saw some you liked at an internship - what was good about them? The layout, the structure of the content, the navigation, was the content printable, searchable, were there example headings, example content? The Flare templates provide a combination of all these things - they provide master pages, and page layouts, and CSS style sheets, and TOCs set up, as well as projects that are mainly print output, or web output, and so on ...

I use templates with Flare, but I have not made them available for download. I took basic Flare project templates and then added our own stylesheet with our corporate logos and colours - this is of no use to anyone else. People have posted items like styles for Notes which are useful, but they are just snippets to be added to a stylesheet, which is available in the supplied templates. Other items we keep in a project template are things like copyright notices - once again, all very company specific.

To get started on a new project, I would create a plan, or content specification. Usually when I write the details of the audience and purpose of the help, and then create content outlines (TOC or topic list), the structure needed evolves. If I need to work on special look and feel or navigation items this would come out of the purpose statement - that would help me create the working plan or schedule of what I would do first, next, etc.

If you need to prove something to management early on, a plan like this with wire-frames or drawings of the final output is usually enough (as a manager, that's what I expect). If you need to prove why it is better than Word, then use your purpose statement that might explain the need for online, or searchability, or it needs to have usable navigation, (there are a million reasons). I realise I don't know your specific managers, but for a first job, a good plan with a schedule will probably keep them happy, and you can usually create that much more quickly than it would take to create the whole project.

[seasonedrookie]

Hmm, well here's the scenario...they have the structure that they are looking for and some content in a Word document. They don't care if I want to make it look better, edit it, reorganize it, etc. I'm having trouble articulating in simple terms why Flare is way better than Word. How should I approach the project with what I have? My instinct says to start with a fresh Flare doc rather than import the existing Word document. If I use a Flare sample template, put in the topics from the existing Word doc into the Flare doc, put in some of the textual content...how do I show them the content in the Flare document and compare it to the existing Word document and explain to them why Flare is better and/or worth the investment. How can I illustrate this to them quickly and easily?

[RamonS]

Can Word generate help output? Does Word have snippets and conditions? Does Word support structured documentation? No to all these questions.
Make a comparison, Word is like the Yugo (http://yugocar.co.uk/yugo-car) and Flare is like a Mercedes Diesel (http://www.mbusa.com/mercedes/benz/green/diesel_bluetec). Sure, both will drive from A to B, but the Yugo falls apart shortly even with regular maintenance, whereas a Diesel Mercedes runs and runs and runs....OK, you could use the VW Beetle here as well, but I rather ride in a Mercedes. Anyhow, pick what you want, any car wins out against a Yugo, maybe not the Trabant (http://www.time.com/time/specials/2007/ ... 30,00.html). So which one would your company chose to transport important guests and customers?
The point is that you can do stuff with Word, but you can do better stuff with much more ease and far more features in Flare. Word makes one look like a n00b, where as Flare is professional. If you deal with folks with an IT background, ask them if they would use a Cisco home router to secure the corporate network. After all, it has a firewall in it, so that will do just fine, right?
Another angle would be to talk about the reason for choosing the right tool to do the work. If the task is to drill a hole into concrete for a pipe to go through, Word would be a mallet and screw driver from Ocean State Job Lot, while Flare is a Bosch Hammer (http://www.boschtools.com/Products/Tool ... px?catid=7). Eventually, you get a hole into the concrete, but it doesn't even take a guess which one gets the job done better, in less time, and with far superior results. Do the developers code C# in Notepad or do they use VisualStudio? After all, in the end we get flat files that get consumed by the compiler.

If you need to convince people about something that they do not have the detailed knowledge about you cannot talk about this or that feature. That woos another tech writer who uses some dinky tool and is willing to switch. If you deal with a group of MBAs, take a look at the ROI studies here: http://idratherbewriting.com/2010/10/27 ... tive-post/, although those cover more the general need for good documentation, which I think seems to be understood.

Yes, Flare is more expensive than Word, but for very good reasons. And why use Word at all, might as well use OpenOffice or LibreOffice and save on MS Office licenses....or Notepad, like the developers.
Unless you have not already done so, show them the output from Word and from Flare. Sure, you could use Word to make a PDF to get the side by side navigation and content plus full text search, but that still does not provide for context sensitive help, which is a standard for any professional software.

As far as templates go, yes, there are nicer ones than those that come with Flare, but I think whatever comes right out of the Flare box is perfectly fine to start with. Prettyfying the output is something to do after the content is in place and things are working fine. Don't buy the paint before you got the wall. And with the defaults you can circumvent a lot of CSS stuff. Besides that, I think having two or three heading styles and some styling to indicate each buttons, commands, and form titles is sufficient. Less is more in that case.

OK, enough of the analogies and product endorsements (well, not really, although I do recommend the Bosch drills, they are awesome!). Now, if you convince your boss(es) to buy Flare let me know and I send you my book as a reward.

[wclass]

This seems to be a different question than the original “best practices” one, so I’m a bit confused about exactly what you are after.

Why is Flare better than Word? Briefly, Flare can produce more output types – webhelp, mobile help, PDF, and Word, to name a few – that can make the content more usable, findable, accessible, etc. Topic based authoring is better for content re-use, for translation, for reviewing and editing, for multiple authors, etc.

To prove this, I’d probably create a project using one of the existing templates, like the Policies and Procedures one as it has some content and styles already set up, and then import the existing engineering documents to show how easy it is to get existing information into a project (note – you can import Word documents into existing projects, you don’t have to create a new project each time). Then I’d generate a few different output targets (at least Webhelp and PDF) to demonstrate the range of output available, which always looks better with your own information, and point out how easy it is to use the content. I’d make some minor changes to the style sheets and skins to get the corporate logo into the project as well.

[i-tietz]

I appreciate the feedback, but I'm running into a problem. I need to get started now and I fear the learning curve will be too slow to keep my managers happy.

Tell the management to go back to their project management classes. It's always the same choice in project management: Either they give you the resource "time" or they will give externals the resource "money". The third resource is, I think, "personnel" - I suppose that's no option in your case. But even if the management decides for outsourcing the concept work: Professional externals cannot get the job done without you knowing what you want ...

So you need to do concept work. From experience I tell you: If you don't spend time on it now, you will have to spend multiples more lateron, when you notice that this or that is lacking or wrong and you will have to change things you already produced.

If you want to do it yourself (or need input for briefing the externals):
You already know a concept you liked. Have you got a copy? Ask the management whether they like it, too. If yes: Take it and find different sorts of paragraphs/elements. To do that you need to categorize them via 3 aspects: Looks, position, behaviour. Start with most common (normal text, numbered list, bullet list, headings, marginal note, link, footnote, image, ... ), then get to the more specific (link to the glossary, warning, table with borders, table with grey background, ... ).

Looks: font, font size, font color, background color, border, underline/bold/italic/...,
Position: position, margin (space around the element on the outside), padding (space around the element on the inside), line height, space before/after,
Behaviour: page-break, orphans/widows, keep with next,

- Do you want to name the styles after their looks or after their purpose?
- Can you find categories for something bigger than a paragraph, let's say, a page (master page layout) or a document (-> template, master page)?

This is only the brainstorming list ... plenty of other things might be possible/necessary. And you will have to write it all down - it's called "style guide". You will need it for reference reasons and as a basis for the external workers - just incase your managers remember their project management lessons.

[i-tietz]

Just find some cohorts, choose a nice cafe to meeting in, and start talking! (It will take some care and feeding, though, to keep it going.)

"The common Flare user - breeding, upbringing and biotope" ... care to write that essay?

[Nita Beck]

"The common Flare user - breeding, upbringing and biotope" ... care to write that essay?

Without meaning to hijack Ryan's thread (sorry, Ryan ), and actually being quite serious in response to the request to write an essay ( ), I am more than happy to chat offline with anyone wishing to start up a Flare user group. I've managed our group since 2009 and have a lot of ideas to share.

[seasonedrookie]

Ugh, what a week. Thanks everybody so much for your advice. It will definitely help me moving forward. It looks like I'm stuck with Word until I can prove the value of Flare. My plan at this point is to toil away with Word during the workweek and try to train myself with Flare on the weekends. I will take the same documentation that I'm creating and structuring in Word and create it with Flare. I'm not going to import the Word documentation, but rather build two separate documents. If nothing else, I'll learn a lot, and continue to be employed. The number one lesson I learned working as a tech writer prior to this job is to be adaptable. I'm trying to keep that lesson in mind. They're not afraid of change here, I just have to make my case with something they are able to see, not envision. I think that will come with time.

Regards,

Ryan S.

[LTinker68]

You can always use MadCap's examples for show-and-tell. You can show them how you can use Flare to create a knowledgebase repository (http://kb.madcapsoftware.com/) and an example of a product help that has all the bells and whistles, like Feedback (http://webhelp.madcapsoftware.com/flare7/Default.htm). The latter includes PDFs built from Flare. You can even show them an example of a CSH call using a map ID (http://kb.madcapsoftware.com/default_CSH.htm#FMP1001F) or by topic name.

[seasonedrookie]

UPDATE:

Hello All,

Just wanted to update you all on the job status. My managers asked me to write a quick proposal for the purchase of MadCap Flare. They were excited by the proposal, investigated the software a bit more seriously, and approved the software purchase! Here is a copy+pasted version of the Word document as the forums won't allow an upload. It's not perfectly written, but it got the job done!

Ryan Xxxx
Technical Writer
XXXXXX Xxxxxxx Xxxxxxxx
February 24, 2012

Proposal for MadCap Flare Technical Authoring Software

Purpose:
The purpose of this proposal is to share information regarding the MadCap Flare technical authoring tool as an alternative to xxxxxxxxxxxxx current tool, Microsoft Word. This proposal will make some comparisons between the two tools and illustrate some of the advantages that MadCap Flare provides.

Cost:
MadCap is currently offering a promotion ending February 29, 2012 where customers can buy their Platinum Customer Service package at a cost of $949 and receive one license for MadCap Flare (ability to run on two machines) for free. Additionally, at a cost of $1,149, customers can buy the Platinum Customer Service package and receive the entire suite of MadCap software products for free. The advantages of the Platinum Customer Support package include: free product updates and upgrades during the 1 year maintenance period, unlimited email support, knowledge base access, forum access, telephone support (unlimited inquiries), dedicated priority email support, dedicated priority telephone support, extended support hours, senior engineer support team, email project for analysis, and invitation to beta releases.

Similar Software:
As a technical writer, I’ve worked for two different companies in an intern capacity. Both of these companies used at least Adobe FrameMaker to create their documentation and my last company was making the transition to a more powerful XML editing tool, ArborText. Currently, the Adobe Technical Communication Suite is offered at a cost of $1,899 which includes no customer support package. As a member of the Society for Technical Communication and from my work with veteran technical writers, I’ve learned that the technical writing field is moving away from the Adobe tools, and that MadCap Flare, among a few others, are leading the way in technical authoring software. This convinced me as a new technical writer to invest my own money in a license for Flare, as well as purchase two training textbooks. MadCap Flare contains an XML editor, which quite simply makes it a much more powerful book/manual creator than Microsoft Word. It was created by the team that created the software that became Adobe’s Robohelp technical authoring tool, but was created from the ground up by one company (MadCap) as opposed to a company (Adobe) attempting to consolidate software created by several different companies. The idea with Flare is that you get an easier to use, streamlined authoring tool.

Comparison to Microsoft Word:
The workflow of a project in Microsoft Word is linear. The document is written from front to back. While this may work okay for one project, if you have multiple projects with similar content, the writer will likely have to re-write the content or attempt to copy and paste the content.
In Flare, the writer can create master pages, copyright pages, page layouts, etc. that are saved as independent parts that can be combined and generated as one file. The same goes for small chunks of content.

For instance, three SOPs; Filtration, Pipeline, and Well Testing are to be created. Much of the front matter will be the same or similar. Perhaps some of the equipment will be used across different manuals. Once a piece of content is written, it is saved as a file and can be simply dragged and dropped into a different manual. Master pages, templates, intro sections, disclaimer pages, equipment sections, etc. can all be written once and easily added or deleted from future, cross-functional/departmental documents.

The xxxxxxxxxxxxxxxxxxxxxxx department may envision the SOPs needing to be set up in different versions in the future. For instance, there may be a need for a version containing information specifically targeted at training, a version specifically targeted at customers, and a condensed, handbook style version for the employees in the field. Further, in 5 years, there may be a need for a version that is able to be easily read on an iPhone. MadCap Flare has the ability to create these different versions of a similar document. Flare is a tool that can get our documentation built and organized in a way that makes future documents much more adaptable than a linearly written Microsoft Word document would allow.

Updates are much more easily added to documents written with Flare. New information is constantly being forwarded to the xxxxxx department for inclusion in the SOP. To add a section or content to a Word document is a chore. The whole 70+ page document is affected. Tables, sections, graphics, etc. are all bumped up and down and are often distorted. This is a significant time/money waster. In Flare, since chunks of content are stored in small pieces, you can open the folder containing just the section on changing the sock filter for example, and the rest of the document will not be affected.

Flare outputs to Word. A fear one may have when switching from Word to another tool is Word .doc files won't be available to fall back on. A major feature of Flare is that it generates Word .doc files. In addition to Word files, Flare can generate PDF, XPS, Adobe FrameMaker, DOCX, XHTML, WebHelp, WebHelp Plus, iPhone, iPad, Microsoft Mobile, Palm Web OS, Blackberry, and Android compatible document files, among others. This gives xxxxxxxxx department options for output. It also allows xxxxx to keep MS Word as the main means of document publishing, but allows the SOP team to create the Word documents in a much more thought-out and manageable way. Further, the xxxxxxxxxxx department would have the ability to take any legacy/old Word documentation and import it into Flare, turning it into XML files, and reuse the legacy content as needed in future documents. Copy and pasting legacy content with Word has already proven to produce problems in the current Filtration draft.

The bugs of Microsoft Word can slow the publishing process. Simple things already seen with the Filtration SOP; apostrophes, quotes, font sizes/styles, etc. have all been distorted inexplicably by Word. Flare utilizes cascading style sheets (CSS) on the backend of the publishing process. CSS basically acts as a filter, forcing all of the text to conform to whatever specifications you specify on the output. Word has features that are supposed to do this, but these features often do not produce the desired results. I have previous experience with CSS and find that it works without as many of the headaches that Word can produce.

Conclusion:
MadCap Flare has the potential to help xxxxxxxxxxxx department save time with the included software/vendor support package. Quick responses to problems are included in the purchase price as opposed to the current situation with Word where time is wasted troubleshooting with no vendor support.

MadCap Flare will save time regarding content management and writing. Sections are written once, tables, graphics, and diagrams are imported once, and then all of these parts can be reused in multiple ways in future documents. The updating process is much easier because the entire manual isn't opened and manipulated, but rather small sections of the document are edited as individual pieces and then published as a whole on the back end of the process.

MadCap Flare solves many of the bug issues experienced with MS Word. Instead of spending time on fixing distorted pieces of the document, it will generate a clean Word document with less trouble because of the way it stores content in folder form.

MadCap Flare better prepares xxxxxxxxxxxxxxxx for the future. One license with the ability to run on two machines is included should xxxxxxxxxx ever hire another writer. The SOP content will be set up to be published in many different formats. Xxxxxxxxxxx will be publishing documents with the latest industry software and will not be limited to Microsoft Word .doc files. Additionally, xxxxxxxxxxx will still have the ability to generate documentation in Word and will have Word files to fall back on should the need arise.

Should you need more information on the advantages of the proposed authoring software, please contact me at xxxxxxxxxxxxxxxx.

[LKupka]

Congratulations Ryan! All very good selling points!

[seasonedrookie]

Congratulations Ryan! All very good selling points!

Lorraine! Thanks! I finally get to devote some time to learning Flare. I'm really excited about it. I downplayed the learning curve in the proposal, so hopefully I can pick it up quick enough to keep any heat off of me.

[LTinker68]

I downplayed the learning curve in the proposal, so hopefully I can pick it up quick enough to keep any heat off of me.

One of the best features (so to speak) of Flare is the fact that the license agreement lets you install Flare on two computers, so long as you're not using Flare simultaneously on those two computers. So you can install Flare on your work computer and install it on your home computer and play with it at home (if you have the time).

[seasonedrookie]

Alright, I'm about to get started with Flare. The Word file I've been building has picked up some eccentricities/bugs along the way and I'm wondering if I'd be best off:
a. typing everything into a Flare doc from scratch
b. stripping all of the formatting from the word doc., then importing into Flare and formatting on that end
c. importing the Word doc as is and hope for the best

It's only a 60-70 page document, so it wouldn't be the end of the world if I had to type everything in. I just want as few troubleshooting issues as possible.

[i-tietz]

Alright, I'm about to get started with Flare. The Word file I've been building has picked up some eccentricities/bugs along the way and I'm wondering if I'd be best off:
a. typing everything into a Flare doc from scratch
b. stripping all of the formatting from the word doc., then importing into Flare and formatting on that end
c. importing the Word doc as is and hope for the best

You can always try out c., but there's one more alternative (at least):
d. Save the Word document as htm and open that one in Flare.

[seasonedrookie]

[/quote]You can always try out c., but there's one more alternative (at least):
d. Save the Word document as htm and open that one in Flare.[/quote]

Ok, what would that do that would save me trouble?

[i-tietz]

You have html tags already, maybe even with classes (I don't know whether Word writes that into a htm file), you wouldn't have to type it all in ... you might even get rid of the funny parts ...
"Saving under" in Word really doesn't take long, so just try it, open the file in a browser (don't look at it in Word) or even copy it into a Flare project and open it with Flare.
If it still looks like an effort, try making an RTF file out of it first, then make it into an htm file.
I remember tables causing some problems, but that was ages ago ...

Since all that doesn't really take long to try out, I would try that before typing all of it manually or reducing it to plain text (ASCII, txt, ...) and then assigning tags and classes for the whole, long document ...