RE: integrating authored content with generated API docs

Subject: RE: integrating authored content with generated API docs
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: Sat, 21 May 2016 23:47:51 -0400

Hi Robert

One of the key design goals for my SPFE project (http://spfeopentoolkit.org)
is the ability to do this type of integration. This takes three forms:

* Support for extract and merge operations in which you algorithmically
combine content extracted from source files (such as JavaDoc) with
structured content written by humans (other than what something like JavaDoc
extracts from comments).

* Support for soft linking of content created by this extract and merge
operation so that, for instance, mentions of a function in a programmers
guide are automatically linked to the relevant entries in the API reference.

* Everything gets published through the same publishing chain, so your API
docs look like everything else.

SPFE is an open source toolkit. You would have to do a fair bit of
integration to get something working with it. It's documentation is also
pretty sparse at this point. I'm guessing you are probably looking for more
of a COTS solution. But as a literal answer to your question, SPFE does this
and I am using it.

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: Saturday, May 21, 2016 1:44 PM
To: TECHWR-L Writing
Subject: integrating authored content with generated API docs

Anybody using a system that does a good job of integrating API docs
generated with javadoc or whatever with human-authored content?

I set up a system with Document!X a few years ago. It let the tech writer
basically wrap the generated doc with additional content and topics, which
were preserved when the generated doc was updated.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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:
integrating authored content with generated API docs: From: Robert Lauriston

Previous by Author: RE: [RMX:NL] Re: [RMX:NL] Re: Request for comments on my Structured Writing series
Next by Author: RE: integrating authored content with generated API docs
Previous by Thread: integrating authored content with generated API docs
Next by Thread: Re: integrating authored content with generated API docs


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

Sponsored Ads


Sponsored Ads