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.
But the software is not the same thing as the models -- the subject-domain
markup languages that let you capture content on a specific topic. The
software is about making everything around the models easier to implement,
because that is crucial, but this is not about writers using the software
(as writers, they would never see it), it is about them using the models.
This is one of the biggest changes and the hardest for people to get their
heads around. People expect to have some application to use, but the
application is a text editor (or an XML editor). Everything else happens in
batch.
To Elisa's point, this is the sort of thing that is second nature to
software developers (which is why API docs are built this way). Their basic
working environment is a text editor where they create structured text that
is processed in batch. It is how they code. It is how they do data. No
wonder it is how they do docs. Markdown, ASCIIDoc, and ReStructuredText were
all invented by developers, as were JavaDoc, Doxygen, etc.
But writers have been trained to think in terms of WYSIWYG publishing tools,
and so giving them batch software and the tools to make modeling easier is
not enough for them to get the point. Thus the need for the book.
This is not at all to claim that I have chosen the ideal sequence to promote
this. Marketing is not my forte. If I get anywhere with this, it will be
through stubbornness, not marketing savvy.
Mark
-----Original Message-----
From: techwr-l-bounces+mbaker=analecta -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+mbaker=analecta -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf
Of Robert Lauriston
Sent: Monday, May 1, 2017 2:25 PM
To: TECHWR-L Writing <techwr-l -at- lists -dot- techwr-l -dot- com>
Subject: Re: Structured stuff for the beginner
In other words, you're putting comprehensive documentation before working
software.
Seems to me you'd get more traction by doing an open-source project.
Then you'd have something tangible to write about.
On Mon, May 1, 2017 at 11:06 AM, <mbaker -at- analecta -dot- com> wrote:
> ... The difficulty is showing people working examples, particularly
> markup-based ones, rather than database-based ones, is certainly one
> of the reasons that progress is stalled in this area. It is a big
> mental leap to make and it is hard to take it on faith when you have
> not had the concrete experience of working on it. Creating more public
> examples is certainly one of the things we need to do to move this
> forward, and it is something I plan to work on once the book is put to
bed. ...
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and
content development | http://techwhirl.com
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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
