Welcome to TechWhirl Forums

Sign in or Register to get involved in our discussions.

If you could select your tools and build your processes from the ground up, what would you do?

I've just been hired as a lone writer at a startup. I'm their first tech writer, ever, and they've been using MediaWiki. It's not ideal. As a lone writer, what tools should I use to create amazing user- and developer-facing documentation?

I'm able to choose to do whatever the hell I want, with the caveat that everyone wants the docs to be gorgeous, well-organized, and easy to use. My model is here. Those docs are beautiful and easy to use. How do I do that? Do I need to go learn front-end development too?

I'm used to writing in DITA, but I'm not sure it makes sense for our documentation, because we don't need to deliver in multiple formats (just web). I'll really miss conditionalizing and conrefs, though. Can I just do that in HTML and forget DITA? (The internet seems to say I need JavaScript...)

I've considered several publishing solutions, including ePub/Webworks/Reverb, easyDITA, FluidTopics, Componize, and even sticking with a wiki like Confluence. None of these solutions appear to enable me to create simple, beautiful, well-organized, minimalist documentation. What gives? Am I missing something? What do you guys use? Do I have to try to convince my devs to build something from scratch? Help!


  • carleecommcarleecomm AustraliaPosts: 4
    What a great question! I'm fascinated to hear what advice people come back with because I find myself in a similar situation. I work for a software company where I'm also a lone writer (and was also the company's first technical writer). But we're expanding rapidly and I'll soon be getting extra writers on my team. 

    I use a CMS developed in-house which makes for an extremely easy-to-use authoring tool (good for our support staff to write internal-facing documentation with little training) and does output beautiful, minimalist documentation... BUT it's lacking a bunch of features that could save me loads of time. 

    I need to talk to our devs about scalability but on the side I'm also looking at different tools that we might be better off switching to now. Unlike you I don't have a background in DITA but some of the XML content authoring tools out there look quite appealing: DITAworks, easyDITA, MadCap Flare, Oxygen XML. I just don't know if it's overkill because, like you, we only publish to web and don't do translation. Also, it's extremely high priority that our docs look gorgeous.

    Here's hoping some other forum members have some handy advice! :)    

  • Ryan MinakerRyan Minaker CanadaPosts: 6
    After many years, and working with pretty much every combination of authoring tools (Word, FrameMaker, RoboHelp, Flare, custom wikis etc). My ideal tool set would be:

    • oXygen XML Editor
    • Snagit (for images)
    • Camtasia (for videos)
    I don't believe there's any situation that's too small for DITA/XML! I don't believe I could ever go back to using anything else.

    *my 2 cents*

  • carleecommcarleecomm AustraliaPosts: 4
    edited January 2015
    So Ryan, are you lucky enough to be using your ideal tool set at the moment - where you work? I'd love to see a sample of your docs.

    As I mentioned above, the visual presentation of our docs is of high importance so I want to know what constraints (if any) an XML HAT would put on our ability to style the docs, with CSS, the way we want to. 
  • On the off chance that anyone here could possibly have an  interest in "dirty hands" tech writing(or, in French, "Les mains sales,not to b e confused with the play by Sartre) where the person reading the directions may be using hand tools to take apart and rebuild mechanical assemblies, in order to accomplish tasks required:

    My tools of choice are Adobe Photoshop, Illustrator, Acrobat and whatever the associated engineering program (the virtual world of 3D modeling) offers as a viewer/interface/bridge to Adobe world. (That last one is almost always the big stumbling block, if the tech writer -- like me -- doesn't have a license for the engineering software, and isn't also a mechanical engineer.)

    Anyway, here's one incredibly useful text manipulation resource I've found for manipulating tab-delimited parts list text
    that could conceivably have applications in software tech writing:

  • GeorgeFlarianGeorgeFlarian United StatesPosts: 16
    Well I will go with  Adobe Photoshop, Illustrator, I have used with my various projects, specifically for responsive stuff .
    like mentioned here:
  • scribetekscribetek United StatesPosts: 1
    I was in a similar situation and I also came from an XML publishing background. Layout power and the ability to output everything from four-color print to HTML5 are of high importance here. I abandoned XML as too limiting and for the last couple of years I've been using Adobe InDesign along with the the rest of the Creative Cloud tools. For collaborative purposes, we create the text in Google Docs and pull that into InDesign. There's a plug-in that provides a two-way link between InDesign and Google Docs. Reviews are handled through a service called Notable. HTML5 output is done through an InDesign plug-in called IN5.

    For video, Camtasia is great.
Sign In or Register to comment.