The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

Modular/reusable documentation?

In http://discuss.joelonsoftware.com/default.asp?design.4.196529.5#discussTopic196671 Mr Analogy said, "most companies don't test (much) and throw the product over the wall to poorly paid tech writers, so the costs of duplicated features is hidden"

My question then is, do you have any thoughts on how (i.e. what tools/techniques to use) to do the same for documentation as a programmer already does with code?

For example: twenty programs have 20 splash screens, which they all implement by each specializing a common splash component ... how then do you import+specialize the documentation for that common component into the 20 design documents, the 20 test plans, the 20 user manuals?
Christopher Wells Send private email
Thursday, September 01, 2005
 
 
When I was a tech writer I did it by literally doing for documentation as I would do for code: i.e. I used a script/macro language to import text fragments, do conditional substitution of variables, etc. That method worked, but:

* You needed to be some kind of programmer to do it
* The 'source code' for the documentation, which consisted of text fragments plus a program to pull selected fragments into various documentation, was more-or-less write-only.

These days I'm wondering if you might do something with, for example, XML-tagged documentation processed by XSLT ... but again:

* You'd have to be some kind of programmer (such 'documentation' couldn't easily be created/generated by end-user-documentation writers, test-case writers, and product-managers)
* It's more-or-less write-only (just as hard as writing code)

So isn't there some premade tool[s] to facilitate this task?
Christopher Wells Send private email
Thursday, September 01, 2005
 
 
Hmmm... sounds like the equivalent of "dynamic web page templates"  for help files. Sounds like a GREAT idea.

I'd like to be able to do a sort o MERGE with my help files.


So my help file might look like>

<merge in 'AdjustingSound.hlp' programname="Foobar">
<merge in 'howToUseHelp.hlp'  programname='foobar'>

Is there anything out there like that? (Please don't say "latex" ;-)  Maybe I need to get around to trying that out ;-)
Mr. Analogy {uISV} Send private email
Thursday, September 01, 2005
 
 
I smell a product idea!!
Mr. Analogy {uISV} Send private email
Thursday, September 01, 2005
 
 
***
I'd like to be able to do a sort o MERGE with my help files.

So my help file might look like>

<merge in 'AdjustingSound.hlp' programname="Foobar">
<merge in 'howToUseHelp.hlp'  programname='foobar'>
***

From Serna online help (Serna is a commercial DocBook editor):
------------------------------------------
>>Working with XInclude<<

XInclude is a mechanism that allows you to aggregate several standalone XML documents into your document. In general XInclude is very similar to external entities , but there are two major differences:
External entities are not self-contained. Within an external entity it is not possible to define DOCTYPE as well as local internal or external entities.
External entities are always included as a whole. In contrast, when xincluding you may merge only a portion of the xincluded document (referenced by XPointer).
------------------------------------------

In general, have a look at DocBook, which I discussed in a thread a couple of days ago.
Paolo Marino Send private email
Friday, September 02, 2005
 
 
>> I smell a product idea!!

Hey, now. Stop that!

There's nothing worse than developing a product and seeing someone **announce to a bunch of developers!** that it would be a good product idea.

My product is a client-server add-in for Word that will be initially targeted at ISO, QS, cGMP, etc. operations that re-use common content across documents.

You can check out my site but there's really not much there yet. It's in the 'emergent' state (aka f'd up), so be gentle.

BTW, I've tentatively named the product DocBreeze (based on the company name), but it's got a cheesy ring to it. If anyone has a better suggestion, please let me know.
Nick Hebb
Friday, September 02, 2005
 
 

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
 
Powered by FogBugz