RE: Structured stuff for the beginner

Subject: RE: Structured stuff for the beginner
From: <mbaker -at- analecta -dot- com>
To: "'Robert Lauriston'" <robert -at- lauriston -dot- com>, "'TECHWR-L Writing'" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 1 May 2017 15:07:13 -0400

"In other words, you're putting comprehensive documentation before working
software."

Not entirely. The working (but not finished) software is here
(https://github.com/mbakeranalecta/spfe-open-toolkit) and here
(https://github.com/mbakeranalecta/sam). Alas, neither of these is yet as
well document as it should be (because making the software work comes
first).

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

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

You are currently subscribed to TECHWR-L as mbaker -at- analecta -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

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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


Follow-Ups:

References:
Re: Structured stuff for the beginner: From: Robert Lauriston
Re: Structured stuff for the beginner: From: Simon North
RE: Structured stuff for the beginner: From: mbaker
Re: Structured stuff for the beginner: From: Robert Lauriston

Previous by Author: RE: Structured stuff for the beginner
Next by Author: RE: Structured stuff for the beginner
Previous by Thread: Re: Structured stuff for the beginner
Next by Thread: Re: Structured stuff for the beginner


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


Sponsored Ads