Re: criteria for choosing tools ?

Subject: Re: criteria for choosing tools ?
From: "Elisa R. Sawyer" <elisawyer -at- gmail -dot- com>
To: Monique Semp <monique -dot- semp -at- earthlink -dot- net>, "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 23 Mar 2017 14:20:49 -0700

Monique, this is late in your process, but since you are incorporating
Markdown and want non-writers to have access, you might want to take a look
at lightweight markup languages:

- Sphinx-doc, which uses Restructured Text:
http://www.sphinx-doc.org/en/stable/
- Asciidoctor, which uses Asiicdoc: http://asciidoctor.org/

These are both popular with developer audiences. I've had situations where
I needed developers to help with first drafts of my doc and using a
lightweight markup language was a big help. I like both of the above and
find that they have slightly different strengths and weaknesses.

With Sphinx-doc, it's easy to create HTML and customize it to harmonize
with an existing web site. Even if you decide to use a different tool for
some of your docs processes, you might find Sphinx-doc to be useful for
creating some of your Web content.

-Elisa

On Mon, Mar 13, 2017 at 5:59 PM, Monique Semp <monique -dot- semp -at- earthlink -dot- net>
wrote:

> Hello, WR-L-ers,
>
> I thought I recalled a somewhat recent discussion about factors to
> consider when choosing tech pubs tools (not just for authoring, but for
> creating/presenting the docs in a âportal-likeâ environment), but I donât
> see it. So Iâll start a new discussion...
>
> I have the rare opportunity to recommend tooling for revamping/creating
> docs (a total of several dozen for the foreseeable future) and making them
> available to customers. So...
>
> Question 1 (of 2)âIâd like to build a big list of criteria so I can rate
> how various tools stack up for our needs. Hereâs my list so far; any more
> suggestions?
>
> a.. Create an organized portal/website w/good navigation.
> b.. Port existing docs from Markdown files in existing Jekyll site.
> c.. Search capability across all docs.
> d.. Analytics (access, bounce rate, etc.).
> e.. Private site requiring authentication.
> f.. Ability to hide some docs from most customers, and make them
> available only when so configured for a given user.
> g.. Mercurial file versioning (no need for an integrated solution; just
> listed here for completeness).
> h.. Mac support (Iâm fine with a Windows VM on my Mac; not sure if they
> will be but I hope so because Flare is an early strong contender).
> i.. Ease-of-use by non-tech-writers (Iâm expecting/hoping that everyone
> will realize that in order to get all the pubsey things done, this is a
> pipe dream, and that itâs analogous to forcing a developer to use Notepad
> instead of a real IDE).
> j.. Supports content reuse at a topic level.
> k.. Supports conditional text (I foresee lots of complex condition sets).
> l.. Supports variables (lots of instructions that are the same for
> multiple supporting/integrated software, so variables will be key to
> publishing all the required combos).
> m.. Organize/sort/tag/categorize docs by several factors: audience
> (admins, developers, etc.), product, product-version, supporting/integrated
> software versions, when used (proof-of-concept, setup/early use, ongoing),
> and so on.
> n.. Generate PDF output, thatâs reasonably pretty, for offline
> distribution.
> o.. Generate HTML output, thatâs easily branded, for online access.
> p.. Fits into CD/CI (continuous development/continuous integration) of
> the SaaS portion of the product suite.
> q.. Handles screenshots by reference.
> r.. Handles artwork files by reference.
> s.. Handles videos (not sure that Iâll create them, but some tasks seem
> made for such a presentation).
> t.. Supports integrating externally-generated HTML mini-sites (produced
> by auto-generators for API references).
> u.. Enable easily adding mechanism for user feedback.
> v.. Supports easy localization management (I donât need it now, but want
> it in the comparison list).
> w.. Creates âaccessibleâ content (per W3C info,
> https://www.w3.org/standards/webdesign/accessibility, and Section 508
> requirements).
> x.. (DITA/related-structure isnât an option; Iâm the lone writer, so Iâm
> not even considering that.)
>
> Question 2 (of 2): Which tools would you include in a side-by-side
> comparison? Iâm thinking:
> a.. MadCap Flare.
> b.. Tech Comm Suite (unstructured).
> c.. Confluence.
> d.. SSG (static site generator) approachâbecause thatâs what they have
> now and itâs Mac-friendly.
>
> Thanks for your input,
> -Monique
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and
> content development | http://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as elisawyer -at- gmail -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> Looking for articles on Technical Communications? Head over to our online
> magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public
> email archives @ http://techwr-l.com/archives
>



--
Elisa Rood Sawyer
~~~~~^~~~~~
Technical and Creative Writer
"Apparently there is nothing that cannot happen today." Mark Twain
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


References:
criteria for choosing tools ?: From: Monique Semp

Previous by Author: Re: Git [was RE: Windows VM on Mac ?]
Next by Author: Re: A question for the list in general
Previous by Thread: RE: criteria for choosing tools ?
Next by Thread: Re: criteria for choosing tools ?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads