TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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:
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
