f	1	[article Soft Documentation	f	1	[article Soft Documentation
n	2	[id softdoc_overload]	n	2	[id softdoc_communicator]
	3	[authors [Guest, Thomas]]		3	[authors [Guest, Thomas]]
	4	[copyright 2006 Thomas Guest]		4	[copyright 2006 Thomas Guest]
	5	]		5	]
	6			6
	7	[def Hibernate [@http://www.hibernate.org Hibernate]]		7	[def Hibernate [@http://www.hibernate.org Hibernate]]
	8	[def DocBook [@http://docbook.org DocBook]]		8	[def DocBook [@http://docbook.org DocBook]]
	9	[def __boost__ [@http://boost.org/ Boost]]		9	[def __boost__ [@http://boost.org/ Boost]]
	10	[def BoostBook [@http://boost.org/tools/boostbook BoostBook]]		10	[def BoostBook [@http://boost.org/tools/boostbook BoostBook]]
	11	[def QuickBook [@http://boost.org/tools/quickbook QuickBook]]		11	[def QuickBook [@http://boost.org/tools/quickbook QuickBook]]
	12	[def --- '''—''']		12	[def --- '''—''']
	13			13
	14	[section Writing a User Manual]		14	[section Writing a User Manual]
	15			15
	16	[section Introduction]		16	[section Introduction]
	17			17
n			n	18	I am a member of a small team of software developers working on a
				19	novel software product (I'll call it "the Product" from now
	18	Recently I spent some time working on a user manual.		20	on). Recently I spent some time working on the user manual for this
				21	Product.
	19			22
n	20	The existing version of this manual was based on a Microsoft Word	n	23	The existing version of the manual was based on a Microsoft Word
	21	master document. From this master the various required output formats		24	master document. From this master the various required output formats
	22	were generated in a semi-automated fashion.		25	were generated in a semi-automated fashion.
	23			26
n	24	I'm guessing anyone who's used a computer will have come across	n	27	Microsoft Word is a popular and powerful tool. It does have its
	25	Microsoft Word: it's a popular tool which is easy to get started with		28	drawbacks though, especially for technical documentation, and these
	26	and which, by virtue of its WYSIWYG interface, allows even a novice to		29	drawbacks were only amplified by the other tools involved in producing
	27	produce stylish output. It does have its drawbacks though, especially		30	the final deliverables. We'll look more closely at these drawbacks
	28	for technical documentation, and these drawbacks were only amplified		31	later. I summarise them here by saying the proprietrary tools and file
	29	by the other tools involved in producing the final deliverables.		32	formats led to a loss of control.
	30			33
n	31	We'll look more closely at these drawbacks later. I summarise them	n	34	Setting up tools to produce technical documentation in multiple
	32	here by saying the proprietrary tools and file formats led to a loss		35	formats is a difficult problem, but it's also a problem which has been
	33	of control. The final outputs were not so much WYSIWYG as		36	solved many times over. Plenty of open source projects provide model
	34	WYGIWYG---What You Get is What You're Given.		37	solutions. My increasing frustration with the Microsoft Word based
	35			38	documentation toolchain led me to explore one of these alternatives.
	36	Producing high quality technical documentation is a difficult problem
	37	but it's also a problem which has been solved many times over. Plenty
	38	of open source projects provide model solutions. My increasing
	39	frustration with the Microsoft Word based documentation toolchain led
	40	me to explore one of these alternatives.
	41			39
	42	This article records the outcome of my exploration. It tells how, in		40	This article records the outcome of my exploration. It tells how, in
	43	the end, we did regain control over the manual, but at a price.		41	the end, we did regain control over the manual, but at a price.
	44			42
	45	[endsect]		43	[endsect]
	46			44
	47	[section Requirements]		45	[section Requirements]
	48			46
n	49	The requirements for the manual were clear enough. It had to look	n	47	The requirements for the manual were clear enough. It had to fit the
	50	good. It had to fit the corporate style---dictating, in this case,		48	corporate style---dictating, in this case, font families, colour
	51	font families, colour schemes, logos and various other presentational		49	schemes and various other presentational aspects. There would be
	52	aspects. There would be pictures. There would be screen shots. There		50	pictures. There would be screen shots. There would be cross
	53	would be cross references.  Naturally, the contents should provide		51	references.  Naturally, the contents should provide clear and complete
	54	clear and complete details on how to use the Product.		52	details on how to use the Product.
	55			53
	56	We needed just two output formats:		54	We needed just two output formats:
	57			55
	58	* hard copy, printed and bound		56	* hard copy, printed and bound
	59	* linked online web pages.		57	* linked online web pages.
	60			58
	61	Of course, these two versions of the document would have to agree with		59	Of course, these two versions of the document would have to agree with
	62	each other. And the Product itself, a server-based piece of software		60	each other. And the Product itself, a server-based piece of software
	63	with a web browser interface, should integrate with the online		61	with a web browser interface, should integrate with the online
	64	documentation in a context-sensitive manner: clicking the Help icon		62	documentation in a context-sensitive manner: clicking the Help icon
	65	next to an item in the UI should pop up the manual opened at the		63	next to an item in the UI should pop up the manual opened at the
	66	correct location.		64	correct location.
	67			65
	68	Finally, there was the slightly strange requirement that the		66	Finally, there was the slightly strange requirement that the
	69	documentation should be substantial [footnote This, to me, is a		67	documentation should be substantial [footnote This, to me, is a
	70	suspect requirement, or at least one we should keep in check,		68	suspect requirement, or at least one we should keep in check,
	71	otherwise we run the risk of producing documentation whose sections		69	otherwise we run the risk of producing documentation whose sections
	72	are cut-and-paste adaptations of similar sections.]. Somehow, it		70	are cut-and-paste adaptations of similar sections.]. Somehow, it
	73	seemed unreasonable to ask customers to hand over lots of money for		71	seemed unreasonable to ask customers to hand over lots of money for
	74	nothing more than CD's worth of software; bundling in a weighty manual		72	nothing more than CD's worth of software; bundling in a weighty manual
	75	made the final deliverables more tangible.		73	made the final deliverables more tangible.
	76			74
	77			75
	78	[endsect]		76	[endsect]
	79			77
	80	[endsect]		78	[endsect]
	81			79
	82	[section Problems with the Existing Documentation Tools]		80	[section Problems with the Existing Documentation Tools]
	83			81
	84	[section The Existing Toolchain]		82	[section The Existing Toolchain]
	85			83
n	86		n
	87	The existing toolchain was, as already mentioned, based on a Microsoft		84	The existing toolchain was, as already mentioned, based on a Microsoft
	88	Word master document. Producing hard copy was as simple as CTRL+P,		85	Word master document. Producing hard copy was as simple as CTRL+P,
	89	followed by a dialog about printer settings and some manual labour		86	followed by a dialog about printer settings and some manual labour
	90	involving a ring binder. It's fair to say that the printed output		87	involving a ring binder. It's fair to say that the printed output
	91	looked pretty much exactly as previewed: the author had good control		88	looked pretty much exactly as previewed: the author had good control
	92	over pagination, positioning of images, fonts, colours and so on.		89	over pagination, positioning of images, fonts, colours and so on.
	93			90
	94	The linked online pages took more effort. We'd got a license for a		91	The linked online pages took more effort. We'd got a license for a
	95	tool which I'll call Word Doctor (not its real name---I'm using an		92	tool which I'll call Word Doctor (not its real name---I'm using an
	96	alias because I'm going to moan about it). Generating the linked web		93	alias because I'm going to moan about it). Generating the linked web
	97	pages using Word Doctor involved the following steps:		94	pages using Word Doctor involved the following steps:
	98			95
	99	# Create a new Project.		96	# Create a new Project.
	100			97
	101	# Point it at the Microsoft Word Master.		98	# Point it at the Microsoft Word Master.
	102			99
	103	# Select some project options from the Word Doctor GUI.		100	# Select some project options from the Word Doctor GUI.
	104			101
n	105	# Click the build button (experts, hit /F5/).	n	102	# Click the build button.
	106			103
	107	# Make a cup of tea while the pages generate.		104	# Make a cup of tea while the pages generate.
	108			105
	109	All fairly easy---in theory. In practice, there were some other steps		106	All fairly easy---in theory. In practice, there were some other steps
	110	which the Word Doctor user manual neglected to mention:		107	which the Word Doctor user manual neglected to mention:
	111			108
	112	# Exit Microsoft Word. Word Doctor has trouble accessing the		109	# Exit Microsoft Word. Word Doctor has trouble accessing the
	113	document otherwise.		110	document otherwise.
	114			111
	115	# Restart your PC. For some reason a resource got terminally locked up.		112	# Restart your PC. For some reason a resource got terminally locked up.
	116			113
	117	# Rewrite the Microsoft Word master using the Word Doctor document		114	# Rewrite the Microsoft Word master using the Word Doctor document
	118	template.		115	template.
	119			116
	120	# Don't forget to exit Microsoft Word!		117	# Don't forget to exit Microsoft Word!
	121			118
	122	# Create a new project etc.		119	# Create a new project etc.
	123			120
	124	# Click the build button.		121	# Click the build button.
	125			122
	126	# Click away a few warnings about saving TEMPLATE.DOT and OLE		123	# Click away a few warnings about saving TEMPLATE.DOT and OLE
	127	something or other.		124	something or other.
	128			125
	129	# Read the Word Doctor workarounds Wiki page on the intranet.		126	# Read the Word Doctor workarounds Wiki page on the intranet.
	130			127
	131	# Click the build button again.		128	# Click the build button again.
	132			129
	133	# Go for lunch. Documentation builds took around half an hour.		130	# Go for lunch. Documentation builds took around half an hour.
	134			131
	135	I am not exaggerating. The engineering manager admitted that he		132	I am not exaggerating. The engineering manager admitted that he
	136	estimated it took at least two days of struggling to convert a		133	estimated it took at least two days of struggling to convert a
	137	Microsoft Word master into the online form. And nor do I blame Word		134	Microsoft Word master into the online form. And nor do I blame Word
n	138	Doctor. I don't think Microsoft Word comes with a decent developer	n	135	Doctor. I don't think Microsoft Word is designed to interoperate with
	139	API. Instead, it tries to do everything itself: from revision control,		136	other thirdparty tools. Instead, it tries to do everything itself:
	140	through styling, to HTML output. It uses an opaque binary file format		137	from revision control, through styling, to HTML output. It uses an
	141	to deter anyone from trying to develop tools to work with it.		138	opaque binary file format to deter anyone from trying to develop tools
				139	to work with it.
	142			140
n	143	The final irritation was with the Word Doctor output---if you ever got	n	141	The final irritation was with the Word Doctor output. The HTML was
	144	any. The HTML was packed with Internet Explorer specific Javascript,		142	packed with Internet Explorer specific Javascript, and looked poor in
	145	and looked poor in any other browser.		143	any other browser.
	146			144
	147	[endsect]		145	[endsect]
	148			146
	149	[section Connecting up to Word Doctor Output]		147	[section Connecting up to Word Doctor Output]
	150			148
	151	The real downside of Word Doctor was when it came to trying to connect		149	The real downside of Word Doctor was when it came to trying to connect
	152	the Product to the Word Doctor web pages. This job fell to me. It was		150	the Product to the Word Doctor web pages. This job fell to me. It was
	153	a multi-layered integration task:		151	a multi-layered integration task:
	154			152
	155	* on a team level I would work with the technical author to ensure the		153	* on a team level I would work with the technical author to ensure the
n	156	documentation content was correct, and contained the required Help	n	154	documentation content was accurate and complete.
	157	topics.
	158			155
	159	* on the Product side, the web-based user interface would call for		156	* on the Product side, the web-based user interface would call for
	160	help using a text identifier. The Help subsystem would use the		157	help using a text identifier. The Help subsystem would use the
n	161	identifier to look up an HTML location---a page and an anchor within	n	158	identifier to look up an HTML location---a page and an anchor within
	162	that page---and it could then pop up a new window viewing this		159	that page---and it could then pop up a new window viewing this
	163	location.		160	location.
	164			161
	165	* on the documentation side, I would have to configure Word Doctor to		162	* on the documentation side, I would have to configure Word Doctor to
	166	ensure its HTML output included the right locations.		163	ensure its HTML output included the right locations.
	167			164
	168	Unfortunately, there were problems with each of these layers.		165	Unfortunately, there were problems with each of these layers.
	169			166
	170	Personally, I got on well with the technical author, but the		167	Personally, I got on well with the technical author, but the
	171	documentation tools made it extremely hard for us to work on the same		168	documentation tools made it extremely hard for us to work on the same
	172	file. We had to take it in turns or work with copies. I couldn't even		169	file. We had to take it in turns or work with copies. I couldn't even
	173	fix a typo directly.		170	fix a typo directly.
	174			171
	175	The Word Doctor output was a frame-based collection of static HTML		172	The Word Doctor output was a frame-based collection of static HTML
	176	pages. Now, externally referencing a particular location in such a set		173	pages. Now, externally referencing a particular location in such a set
	177	of pages is tricky---due to the limitations of frames---so the		174	of pages is tricky---due to the limitations of frames---so the
	178	Product's help sub-system had to dynamically generate a framed front		175	Product's help sub-system had to dynamically generate a framed front
	179	page displaying the appropriate left and right pane each time it was		176	page displaying the appropriate left and right pane each time it was
	180	called. Not too difficult, but more complex than strictly necessary.		177	called. Not too difficult, but more complex than strictly necessary.
	181			178
	182	Both pages and anchors were a moving target in the Word Doctor		179	Both pages and anchors were a moving target in the Word Doctor
n	183	output. Every time you added a new section to the document you broke	n	180	output. Every time you added a new section to the document you risked
	184	most of the help references. Thus we found ourselves in a situation		181	breaking the help references. Thus we found ourselves in a situation
	185	where the technical author wanted the Product to stabilise in order to		182	where the technical author wanted the Product to stabilise in order to
n	186	document it and I needed the documentation to stabilise in order to	n	183	document it and I needed the documentation to stabilise so that the
	187	link to it.		184	Product could link to it.
	188			185
	189	[endsect]		186	[endsect]
	190			187
	191	[section Other Problems]		188	[section Other Problems]
	192			189
	193	Microsoft Word uses a proprietary binary format. This ties you into		190	Microsoft Word uses a proprietary binary format. This ties you into
	194	their product to a degree---effectively, you're relying on Microsoft		191	their product to a degree---effectively, you're relying on Microsoft
	195	to look after your data because you simply cannot work with this data		192	to look after your data because you simply cannot work with this data
	196	without their tool. Of course, the risk of Microsoft collapsing during		193	without their tool. Of course, the risk of Microsoft collapsing during
	197	the lifetime of your document may be one you can live with, but you		194	the lifetime of your document may be one you can live with, but you
	198	are also vulnerable to them ceasing to support the version of Word you		195	are also vulnerable to them ceasing to support the version of Word you
	199	prefer, or charging an unreasonable amoount for an upgrade. It also		196	prefer, or charging an unreasonable amoount for an upgrade. It also
	200	means:		197	means:
	201			198
	202	* it's extremely hard for more than one person to work on a document		199	* it's extremely hard for more than one person to work on a document
	203	at a time since changes to binary files cannot be merged together		200	at a time since changes to binary files cannot be merged together
	204	easily.		201	easily.
	205			202
	206	* revision control becomes more expensive and less useful (how do you		203	* revision control becomes more expensive and less useful (how do you
	207	view the differences between two versions of the manual?)		204	view the differences between two versions of the manual?)
	208			205
	209	* it is very difficult to automate anything. As a trivial example,		206	* it is very difficult to automate anything. As a trivial example,
	210	Word Doctor had no batch interface---it required human input at		207	Word Doctor had no batch interface---it required human input at
	211	every stage. Now consider trying to rebadge the manual, perhaps for		208	every stage. Now consider trying to rebadge the manual, perhaps for
	212	redistribution of the Product by some partner company. With a decent		209	redistribution of the Product by some partner company. With a decent
	213	documentation toolchain this should be as simple as the build		210	documentation toolchain this should be as simple as the build
	214	`prepare` target copying the correct logo graphic into place and		211	`prepare` target copying the correct logo graphic into place and
	215	applying a simple transformation to some text strings.		212	applying a simple transformation to some text strings.
	216			213
	217	[endsect]		214	[endsect]
	218			215
	219	[section Resistance to Change]		216	[section Resistance to Change]
	220			217
	221	Despite all of these limitations and irritations it was hard to convince		218	Despite all of these limitations and irritations it was hard to convince
	222	anyone a change was necessary or even desirable. The reasons were as muc		219	anyone a change was necessary or even desirable. The reasons were as muc
	>	h		>	h
	223	organisational as technical.		220	organisational as technical.
	224			221
	225	* The existing tools had been used to produce acceptable end user		222	* The existing tools had been used to produce acceptable end user
	226	documentation in the past for other products shipped by the company.		223	documentation in the past for other products shipped by the company.
	227			224
	228	* Already, considerable effort had been put into the Word master for		225	* Already, considerable effort had been put into the Word master for
	229	the new Product (even if much of it would have to be scrapped due to		226	the new Product (even if much of it would have to be scrapped due to
	230	the inevitable changes as the Product developed).		227	the inevitable changes as the Product developed).
	231			228
n	232	* The engineering team had more work than it could cope with	n
	233	already. At least the user documentation could be outsourced to a
	234	contract technical author.
	235
	236	* Setting up a smarter toolchain would need engineering input, and,		229	* Setting up a smarter toolchain would need engineering input, and,
	237	once the tools were in place, would the technical author be able to		230	once the tools were in place, would the technical author be able to
	238	use them productively?		231	use them productively?
	239			232
n	240	* The sales team saw the documentation task as non-urgent for much the	n
	241	same reason that they saw user input validation as a nice-to-have
	242	rather than a priority. After all, they'd run some promising beta
	243	trials at customer sites using a poorly documented and
	244	inputs-unchecked version of the Product. They were happy to continue
	245	to provide support and tuition as required, either on site, by phone
	246	or by email.
	247
	248	I could (and did) argue against all of these points:		233	I could (and did) argue against all of these points:
	249			234
	250	* Existing documentation was stand-alone: it did not have to integrate		235	* Existing documentation was stand-alone: it did not have to integrate
	251	with what it documented.		236	with what it documented.
	252			237
n	253	* Using the existing tools to connect the new Product with	n	238	* Using the existing tools to connect the Product with
	254	its documentation looked like being a continual sink of effort.		239	its documentation looked like being a continual sink of effort.
	255			240
n	256	* The engineering team probably spent as long telling the technical	n	241	* I had every confidence that the technical author could quickly
	257	author what to write as they might have spent writing it themselves.		242	master a new documentation tool, and that such a tool would save us
				243	all time even in the short term.
	258			244
n	259	* Surely the technical author would quickly master a new documentation	n	245	As I saw it, we risked treating documentation as an add-on---a
	260	tool?		246	nice-to-have---rather than as an integral part of the Product, and I
	261			247	believe this is wrong. Decent documentation is one of the first things
	262	* In fact it was more often the engineers than the sales team who provid		248	I look for when I evaluate a piece of software. Quite simply, I didn't
	>	ed
	263	support, and frequently for problems which could have been avoided wit		249	want to deliver a Product with poor documentation.
	>	h
	264	better input checking and more solid documentation.
	265
	266	As software engineers we need to concentrate on the software. That
	267	means listening to the sales team; but when it comes to software
	268	quality, we know best. I believe the only shortcut is to prune back
	269	the feature list and, increasingly, I regard it as wrong to view
	270	software documentation as an add-on. Decent documentation is one of
	271	the first things I look for when I evaluate a piece of software: the
	272	website, the user interface, the README, the FAQ list, and of course
	273	the source code itself (if available). Quite simply, I didn't want to
	274	deliver a Product with poor documentation. I didn't think it would
	275	save us time in the short or long term.
	276			250
	277	[endsect]		251	[endsect]
	278			252
	279	[endsect]		253	[endsect]
	280			254
	281	[section Regaining Control]		255	[section Regaining Control]
	282			256
	283	My frustration with the existing documentation tools set me thinking		257	My frustration with the existing documentation tools set me thinking
	284	about alternatives. I looked first to the open source world, where		258	about alternatives. I looked first to the open source world, where
	285	there's no shortage of excellent documentation and where the authors		259	there's no shortage of excellent documentation and where the authors
	286	are happy to show how they generated it.		260	are happy to show how they generated it.
	287			261
	288	I experimented by downloading and attempting to build some open source		262	I experimented by downloading and attempting to build some open source
n	289	documentation. This was a part time activity, squeezed into moments	n	263	documentation. Once I had this basic step working, I continued to
	290	when I was waiting for builds to complete or files to check out. If		264	experiment. Could I change fonts, include images, replicate the house
	291	the documentation didn't build or required lots of configuration to		265	style? How easy were the tools to use with our own content?
	292	get it to build, I moved on.  I was looking for something as simple
	293	as:
	294
	295	[pre
	296	> cd docs ; make
	297	]
	298
	299	To my surprise and disappointment it took several attempts to find
	300	something which worked out of the box. Perhaps I was unlucky. No doubt
	301	in many cases it was user error on my part and no doubt I could have
	302	sought advice from email lists; nonetheless, I kept moving on until I
	303	found something which worked first time (my thanks to the Hibernate
	304	documentation team). Then I continued to experiment: could I change
	305	fonts, include images, replicate the house style? How easy were the
	306	tools to use with our own content?
	307			266
	308	After a Friday afternoon's experimentation I had something worth		267	After a Friday afternoon's experimentation I had something worth
	309	showing to the engineering manager: an end-to-end solution which, from		268	showing to the engineering manager: an end-to-end solution which, from
	310	a DocBook XML master, generated a skeleton PDF and HTML user manual in		269	a DocBook XML master, generated a skeleton PDF and HTML user manual in
	311	something approaching the house style.		270	something approaching the house style.
	312			271
	313	I suggested to the engineering manager that we should switch the		272	I suggested to the engineering manager that we should switch the
n	314	usermanual to use the tools I had just demonstrated. I said I'd be	n	273	usermanual to be based on the tools I had just demonstrated. I said
	315	happy to do the work. He agreed with me that technically, this seemed		274	I'd be happy set up the toolchain. He agreed with me that technically,
	316	the way forwards. However, it wasn't easy for him to give me the go		275	this seemed the way forwards. However, it wasn't easy for him to give
	317	ahead for the reasons already discussed.  Also, it was a hard sell for		276	me the go ahead for the reasons already discussed.
	318	him to make to the rest of the company: on the one hand, writing end
	319	user documentation simply wasn't what the engineers were supposed to
	320	be doing; and on the other, it was hard enough persuading the
	321	technical author to use the revision control system, let alone edit
	322	raw XML.
	323			277
	324	I confess I had my own doubts too. All I knew at this stage was that		278	I confess I had my own doubts too. All I knew at this stage was that
	325	DocBook could do the job and that I would happily tinker with it to		279	DocBook could do the job and that I would happily tinker with it to
n	326	get it working. I didn't know if I could be productive using it. I	n	280	get it working for us. I didn't know if we could be productive using
	327	don't relish editing XML either.		281	it. At least we understood the limitations of the current tools.
	328			282
	329	We both recognised that the single most important thing was		283	We both recognised that the single most important thing was
	330	content. Full and accurate documentation supplied as a plain README		284	content. Full and accurate documentation supplied as a plain README
	331	would be of more practical use to our customers than something		285	would be of more practical use to our customers than something
	332	beautifully formatted and structured but misleadingly inaccurate.		286	beautifully formatted and structured but misleadingly inaccurate.
	333			287
	334	In the end we deferred making a final decision on what to do with the		288	In the end we deferred making a final decision on what to do with the
	335	manual.  The results of my experiment did seem worth recording, so I		289	manual.  The results of my experiment did seem worth recording, so I
	336	spent a day or so tidying up and checking in the code so we could		290	spent a day or so tidying up and checking in the code so we could
	337	return to it, if required.		291	return to it, if required.
	338			292
	339	[endsect]		293	[endsect]
	340			294
	341	[section A DocBook Toolchain]		295	[section A DocBook Toolchain]
	342			296
	343	I should outline here the basics of the toolchain I had evaluated. It		297	I should outline here the basics of the toolchain I had evaluated. It
	344	was based on DocBook. A two sentence introduction to DocBook can be		298	was based on DocBook. A two sentence introduction to DocBook can be
	345	found on the front page of the [@http://docbook.sourceforge.net/		299	found on the front page of the [@http://docbook.sourceforge.net/
	346	SourceForge DocBook Project].  I reproduce it here in full:		300	SourceForge DocBook Project].  I reproduce it here in full:
	347			301
	348	[:DocBook is an XML vocabulary that lets you create documents in a		302	[:DocBook is an XML vocabulary that lets you create documents in a
	349	presentation-neutral form that captures the logical structure of your		303	presentation-neutral form that captures the logical structure of your
	350	content. Using free tools along with the DocBook XSL stylesheets, you		304	content. Using free tools along with the DocBook XSL stylesheets, you
	351	can publish your content as HTML pages and PDF files, and in many		305	can publish your content as HTML pages and PDF files, and in many
	352	other formats.]		306	other formats.]
	353			307
	354	I would also like to highlight a couple of points from the preface to		308	I would also like to highlight a couple of points from the preface to
	355	Bob Stayton's [@http://www.sagehill.net/docbookxsl/index.html		309	Bob Stayton's [@http://www.sagehill.net/docbookxsl/index.html
	356	['DocBook XSL: The Complete Guide]]---a reference which anyone		310	['DocBook XSL: The Complete Guide]]---a reference which anyone
	357	actually using DocBook is sure to have bookmarked:		311	actually using DocBook is sure to have bookmarked:
	358			312
	359	[:A major advantage of DocBook is the availability of DocBook tools		313	[:A major advantage of DocBook is the availability of DocBook tools
	360	from many sources, not just from a single vendor of a proprietary file		314	from many sources, not just from a single vendor of a proprietary file
	361	format.  You can mix and match components for editing, typesetting,		315	format.  You can mix and match components for editing, typesetting,
	362	version control, and HTML conversion.\n ...  \nThe other major		316	version control, and HTML conversion.\n ...  \nThe other major
	363	advantage of DocBook is the set of free stylesheets that are available		317	advantage of DocBook is the set of free stylesheets that are available
	364	for it... These stylesheets enable anyone to publish their DocBook		318	for it... These stylesheets enable anyone to publish their DocBook
	365	content in print and HTML. An active community of users and		319	content in print and HTML. An active community of users and
	366	contributors keeps up the development of the stylesheets and answers		320	contributors keeps up the development of the stylesheets and answers
	367	questions.]		321	questions.]
	368			322
	369	So, the master document is written in XML conforming to the DocBook		323	So, the master document is written in XML conforming to the DocBook
	370	DTD. This master provides the structure and content of our		324	DTD. This master provides the structure and content of our
	371	document. Transforming the master into different output formats starts		325	document. Transforming the master into different output formats starts
	372	with the DocBook XSL stylesheets.  Various aspects of the		326	with the DocBook XSL stylesheets.  Various aspects of the
	373	transformation can be controlled by setting parameters to be applied		327	transformation can be controlled by setting parameters to be applied
	374	during this transformation (do we want a datestamp to appear in the		328	during this transformation (do we want a datestamp to appear in the
	375	page footer?, should a list of Figures be included in the contents?),		329	page footer?, should a list of Figures be included in the contents?),
	376	or even by writing custom XSL templates (for the front page, perhaps).		330	or even by writing custom XSL templates (for the front page, perhaps).
	377			331
	378	Depending on the exact output format there may still be work for us to		332	Depending on the exact output format there may still be work for us to
	379	do.  For HTML pages, the XSL transformation produces nicely structured		333	do.  For HTML pages, the XSL transformation produces nicely structured
	380	HTML, but we probably want to adjust the CSS style sheet and perhaps		334	HTML, but we probably want to adjust the CSS style sheet and perhaps
	381	provide our own admonition and navigation graphics. For Windows HTML		335	provide our own admonition and navigation graphics. For Windows HTML
	382	Help, the DocBook XSL stylesheets again produce a special form of HTML		336	Help, the DocBook XSL stylesheets again produce a special form of HTML
	383	which we must then run through an HTML Help compiler.		337	which we must then run through an HTML Help compiler.
	384			338
	385	PDF output is rather more fiddly: The DocBook XSL stylesheets yield		339	PDF output is rather more fiddly: The DocBook XSL stylesheets yield
	386	XSL formatting objects (FO) from the DocBook XML master. A further		340	XSL formatting objects (FO) from the DocBook XML master. A further
	387	stage of processing is then required to convert these formatting		341	stage of processing is then required to convert these formatting
	388	objects into PDF. I used the [@http://xmlgraphics.apache.org/fop/		342	objects into PDF. I used the [@http://xmlgraphics.apache.org/fop/
	389	Apache Formatting Objects Processor (FOP)], which in turn depends on		343	Apache Formatting Objects Processor (FOP)], which in turn depends on
	390	other third-party libraries for image processing and so on.		344	other third-party libraries for image processing and so on.
	391			345
	392	As we can see, there are choices to be made at all stages: which XSL		346	As we can see, there are choices to be made at all stages: which XSL
	393	transform software do we use, which imaging libraries; do we go for a		347	transform software do we use, which imaging libraries; do we go for a
	394	stable release of Apache FOP or the development rewrite? Do we spend		348	stable release of Apache FOP or the development rewrite? Do we spend
	395	money on a DocBook XML editor? Since we have full source access for		349	money on a DocBook XML editor? Since we have full source access for
	396	everything in the chain we might also choose to customise the tools if		350	everything in the chain we might also choose to customise the tools if
	397	they aren't working for us.		351	they aren't working for us.
	398			352
n	399	These choices were, to start with, a distraction. I was happy to go	n	353	These choices were, to start with, a distraction.  I wanted the most
	400	with the selection made by the Hibernate team unless there was a good		354	direct route to generating decent documentation. I kept reminding
	401	reason not to. I wanted the most direct route to generating decent		355	myself that content was more important than style (even though the
	402	documentation. I kept reminding myself that content was more important
	403	than style (even though the styling tools were more fun to play with).		356	styling tools were more fun to play with).
	404			357
	405	[endsect]		358	[endsect]
	406			359
n	407	[section Sidebar: Presentation and Structure]	n	360	[section Sidebar: Version Control]
	408
	409	A key point to realise when writing technical documentation is the
	410	distinction between structure and presentation. Suppose, for example,
	411	our document includes source code snippets and we want these snippets
	412	to be preformatted in a monospaced font with keywords emphasized using
	413	a bold font style. Here, we have two structural elements (source code,
	414	keywords) and two presentational elements (monospaced font, bold
	415	style).
	416
	417	Structure and presentation are separate concerns and our documentation
	418	chain should enable and maintain this distinction. This means that our
	419	master document structure will need to identify source code as "source
	420	code"---and not simply as preformatted text---and any keywords within
	421	it as "keywords"; and the styling associated with the presentation of
	422	this document will make the required mapping from "source code" to
	423	"monospace, preformatted" and from "keyword" to "bold".
	424
	425	We can see this separation in well-written HTML where the familiar
	426	element tags (HEAD, BODY, H1, H2, P etc) describe basic document
	427	structure, and CLASS attributes make finer structural
	428	distinctions. The actual presentation of this structured content is
	429	controlled by logically (and usually physically) separate Cascading
	430	Style Sheets (CSS).
	431			361
n	432	With a WYSIWYG documentation tool presentation and structure---by	n	362	Software must adapt to survive. Features are added, bugs squashed;
	433	definition---operate in tandem, making it all too easy to use a		363	maybe the UI gets a makeover, maybe configuration files are replaced
	434	structural hack to fix a presentational issue (for example,		364	by a database. Customers do not usually get exposed to this state of
	435	introducing a hard page break to improve printed layout, or scaling a		365	flux. Typically, they are shipped stable and tested versions of a
	436	font down a point size to make a table look pretty).		366	Product---though they may also expect to receive patches against these
	437			367	versions, fixing critical bugs for example.
	438	DocBook enforces the separation between structure and presentation		368
	439	strictly. This doesn't mean that we can't use a Graphical Editor to		369	Software developers depend on their version control system to manage
	440	work with DocBook documents---indeed, a web search suggests several		370	both the formal, released versions, the patches, and the ongoing
	441	such editors exist. I chose to work with the raw DocBook format,		371	development version, and to maintain the connections between these
	442	however, partly because I could continue to use my		372	versions. Computers are good at isolating the differences between
	443	[@http://www.gnu.org/software/emacs/emacs.html preferred editor]		373	versions of a source file and at copying these differences between the
	444	and partly because I wanted to get a better		374	different branches of a code-base. Thus, a programmer can (for
	445	understanding of DocBook. The enforced separation can sometimes be		375	example) fix a bug once, and the version control system can then be
	446	frustrating, however.  It took me about an hour to figure out how to		376	used to safely apply the fix wherever it's needed.
	447	disable hyphenation of the book's subtitle on my custom frontpage!		377
				378	In a large code base, the version control system can be configured to
				379	allow a team of programmers to work on the same set of files---and
				380	even on the same file.  The version control system can make sense of
				381	concurrent modifications, and merge them accurately; and in the rare
				382	situations it can't, it fails safely.
				383
				384	These considerations apply equally to the user manual, whose
				385	versions must map to versions of the software. By choosing suitable
				386	documentation formats and adopting version control, authors can
				387	realise the same benefits.
				388
				389	In fact, the leading open source version control system, Subversion
				390	[Reference: Subversion], explains the concept of branching a project
				391	using the particular example of a document -- a handbook, in this
				392	case. See:
				393	http://svnbook.red-bean.com/en/1.1/ch04.html#svn-ch-4-sect-1 for
				394	more information.  Note also that the Subversion documentation is
				395	written in DocBook.
	448			396
	449	[endsect]		397	[endsect]
	450			398
	451	[section The Technical Author Departs]		399	[section The Technical Author Departs]
	452			400
	453	We continued on, then, deferring work on the documentation until at		401	We continued on, then, deferring work on the documentation until at
n	454	least we had frozen the user interface, still pinning our hopes on	n	402	least we had frozen the user interface. Then the technical author
	455	Word Doctor. Then the technical author left. She'd landed a full-time		403	left. She'd landed a full-time editing position on a magazine.
	456	editing position on a magazine.
	457			404
	458	Again, I volunteered to work on the documentation. By now the		405	Again, I volunteered to work on the documentation. By now the
	459	engineering manager had succeeded in selling the idea of switching		406	engineering manager had succeeded in selling the idea of switching
n	460	documentation tools to higher management. It was still hard for him to	n	407	documentation tools to higher management.
	461	authorise me to actually write the documentation, though, since we had
	462	just recruited a new technical support engineer, based in North
	463	America. This engineer had nothing particular lined up for the next
	464	couple of weeks. What better way for him to learn about the Product
	465	than to write the user manual?
	466			408
n	467	As it turned out it various delayed hardware deliveries meant it took	n
	468	him a couple of weeks to set up a server capable of actually running
	469	the Product---and then he was booked up on site visits. He didn't get
	470	to spend any time on documentation.
	471
	472	Version 1.0 was due to be released in a week's time. We had four chices:		409	Version 1.0 was due to be released in two weeks. We had four choices:
	473			410
	474	# Ship with the existing documentation---which was dangerously out of		411	# Ship with the existing documentation---which was dangerously out of
	475	date.		412	date.
	476			413
	477	# Stub out the documentation entirely, so at least users wouldn't be		414	# Stub out the documentation entirely, so at least users wouldn't be
	478	misled by it.		415	misled by it.
	479			416
	480	# Revise the Microsoft Word document, use Word Doctor to generate HTML,		417	# Revise the Microsoft Word document, use Word Doctor to generate HTML,
	481	reconnect the HTML to the Product.		418	reconnect the HTML to the Product.
	482			419
	483	# Rewrite the manual using DocBook.		420	# Rewrite the manual using DocBook.
	484			421
	485	We ruled out the first choice even though it required the least		422	We ruled out the first choice even though it required the least
	486	effort. The second seemed like an admission of defeat---could we		423	effort. The second seemed like an admission of defeat---could we
	487	seriously consider releasing a formal version of the Product without		424	seriously consider releasing a formal version of the Product without
	488	documentation? Noone present had any enthusiasm for the third choice.		425	documentation? Noone present had any enthusiasm for the third choice.
	489			426
n	490	So, finally, with less than a week until code freeze, I got assigned	n	427	So, finally, with less than a fortnight until code-freeze, I got
	491	the task of finishing the documentation using the tools of my		428	assigned the task of finishing the documentation using the tools of my
	492	choosing.		429	choosing.
n			n	430
	493			431
	494	[endsect]		432	[endsect]
	495			433
	496	[section Problems with DocBook]		434	[section Problems with DocBook]
	497			435
	498	Most things went rather suprisingly well, but I did encounter a small		436	Most things went rather suprisingly well, but I did encounter a small
	499	number of hitches.		437	number of hitches.
	500			438
	501	[section Portability]		439	[section Portability]
	502			440
	503	My first unpleasant surprise with the DocBook toolchain came when I		441	My first unpleasant surprise with the DocBook toolchain came when I
	504	tried to generate the printable PDF output on a Windows XP		442	tried to generate the printable PDF output on a Windows XP
	505	machine. Rather naively, perhaps, I'd assumed that since all the		443	machine. Rather naively, perhaps, I'd assumed that since all the
	506	tools were Java based I'd be able to run them on any platform with a		444	tools were Java based I'd be able to run them on any platform with a
	507	JVM. Not so.		445	JVM. Not so.
	508			446
n	509	The first time I tried a Windows build, I got a two page traceback which	n	447	The first time I tried a Windows build, I got a two page traceback
	510	sliced through methods in [^javax.media.jai], [^org.apache.fop.pdf],		448	triggered by an exception raised in one of the graphics processing
	511	[^org.apache.xerces.parsers], arriving finally at the cause:		449	libraries. Fortunately, I was able to work around the problem by
	512			450	swapping the graphics library for an alternative version, apparently
	513	[pre		451	with no adverse effects.
	514	Caused by: java.lang.IllegalArgumentException: Invalid ICC Profile D
	>	ata
	515	at java.awt.color.ICC_Profile.getInstance(ICC_Profile.java:873)
	516	at java.awt.color.ICC_Profile.getInstance(ICC_Profile.java:841)
	517	at java.awt.color.ICC_Profile.getDeferredInstance(ICC_Profile.jav
	>	a:929)
	518	at java.awt.color.ICC_Profile.getInstance(ICC_Profile.java:759)
	519	at java.awt.color.ColorSpace.getInstance(ColorSpace.java:278)
	520	at java.awt.image.ColorModel.<init>(ColorModel.java:151)
	521	at java.awt.image.ComponentColorModel.<init>(ComponentColorModel.
	>	java:256)
	522	at com.sun.media.jai.codec.ImageCodec.<clinit>(ImageCodec.java:56
	>	1)
	523	... 34 more
	524	]
	525
	526	I had several options here: web search for a solution, raise a query
	527	on an email list, swap out the defective component in the toolchain,
	528	roll up my sleeves and debug the problem, or restrict the
	529	documentation build to Linux only.
	530
	531	I discovered this problem quite early on, before the technical author
	532	left---otherwise the Linux-only build restriction might have been an
	533	acceptable compromise; several other Product components were by now
	534	tied to Linux. (Bear in mind that the documentation build /outputs/
	535	were entirely portable, it was only the build itself which didn't work
	536	on all platforms). My actual solution was, though, another compromise:
	537	I swapped the [@http://java.sun.com/products/java-media/jai/ JAI]
	538	libraries for the more primitive [http://java.sun.com/products/jimi/
	539	JIMI] ones, apparently with no adverse effects.
	540			452
	541	The incident did shake my confidence, though. It may well be true that		453	The incident did shake my confidence, though. It may well be true that
n	542	open source tools allow you the ultimate level of control, but you	n	454	open source tools give you the ultimate level of control, but you
	543	don't usually want to exercise it! At this stage I had only tried		455	don't usually want to exercise it! At this stage I had only tried
	544	building small documents with a few images. I remained fearful that		456	building small documents with a few images. I remained fearful that
	545	similar problems might recur when the manual grew larger and more		457	similar problems might recur when the manual grew larger and more
	546	laden with screenshots.		458	laden with screenshots.
	547			459
	548	[endsect]		460	[endsect]
	549			461
	550	[section Volatility]		462	[section Volatility]
	551			463
	552	We all know that healthy software tools are in active development, but		464	We all know that healthy software tools are in active development, but
	553	this does have a downside. Some problems actually arose from the		465	this does have a downside. Some problems actually arose from the
	554	progression of the tools I was using. For example, I started out with		466	progression of the tools I was using. For example, I started out with
n	555	the version of the DocBook XSL stylesheets I found in the Hibernate	n	467	the version of the DocBook XSL stylesheets I scavenged from my
	556	distribution (version 1.65.1).		468	reference open source documentation build (version 1.65.1).
	557			469
	558	These were more than good enough for my needs, but much of the DocBook		470	These were more than good enough for my needs, but much of the DocBook
	559	documentation I was using referred to more recent distributions. In		471	documentation I was using referred to more recent distributions. In
	560	this case, switching to the most recent stable distribution of the XSL		472	this case, switching to the most recent stable distribution of the XSL
	561	stylesheets resulted in improvements all round. Apache FOP is less		473	stylesheets resulted in improvements all round. Apache FOP is less
	562	mature though: the last stable version (as of December 2005) is		474	mature though: the last stable version (as of December 2005) is
	563	0.20.5---hardly a version number to inspire confidence---and the		475	0.20.5---hardly a version number to inspire confidence---and the
	564	latest release, 0.90 alpha 1, represents a break from the past. I		476	latest release, 0.90 alpha 1, represents a break from the past. I
	565	anticipate problems if and when I migrate to a modern version of FOP,		477	anticipate problems if and when I migrate to a modern version of FOP,
	566	though again, I also hope for improvements.		478	though again, I also hope for improvements.
	567			479
	568	[endsect]		480	[endsect]
	569			481
	570	[section Verbosity]		482	[section Verbosity]
	571			483
	572	XML is verbose and DocBook XML is no exception. As an illustration, here		484	XML is verbose and DocBook XML is no exception. As an illustration, here
	573	is a section of a DocBook document:		485	is a section of a DocBook document:
	574			486
	575	[pre		487	[pre
n	576	<section id="hello_world">	n
	577	<title>Hello World</title>
	578	<para>		488	<para>
	579	Here is the canonical C++ example program.		489	We needed just two output formats:
	580	</para>		490	</para>
	581	<programlisting>		491	<itemizedlist>
	582	<!\[CDATA\[		492	<listitem>
	583	#include <iostream>		493	hard copy, printed and bound
	584			494	</listitem>
	585	int main() {		495	<listitem>
	586	std::cout << "Hello world!" << std::endl;		496	linked online web pages.
	587	return 0;		497	</listitem>
	588	}		498	</itemizedlist>
	589	\]\]>
	590	</programlisting>
	591	</section>
	592	]		499	]
	593			500
	594	XML claims to be human readable, and on one level, it is. On another		501	XML claims to be human readable, and on one level, it is. On another
	595	level, though, the clunky angle brackets and obtrusive tags make the		502	level, though, the clunky angle brackets and obtrusive tags make the
	596	actual text content in the master document hard to read: the syntax		503	actual text content in the master document hard to read: the syntax
	597	obscures the semantics.		504	obscures the semantics.
n			n	505
	598			506
	599	[endsect]		507	[endsect]
	600			508
	601	[section Control]		509	[section Control]
	602			510
	603	The DocBook toolchain gave us superb control over some aspects of the		511	The DocBook toolchain gave us superb control over some aspects of the
	604	documentation task. In other areas the controls existed but were		512	documentation task. In other areas the controls existed but were
	605	tricky to locate and operate.		513	tricky to locate and operate.
	606			514
	607	For example, controlling the chunking of the HTML output was		515	For example, controlling the chunking of the HTML output was
	608	straightforward and could all be done using build time		516	straightforward and could all be done using build time
	609	parameters---with no modifications needed to the document		517	parameters---with no modifications needed to the document
	610	source. Similarly, controlling file and anchor names in the generated		518	source. Similarly, controlling file and anchor names in the generated
	611	HTML was easy, which meant the integration between the Product and the		519	HTML was easy, which meant the integration between the Product and the
	612	online version of the manual was both stable and clean.		520	online version of the manual was both stable and clean.
	613			521
	614	Some of the printed output options don't seem so simple, especially		522	Some of the printed output options don't seem so simple, especially
	615	for someone without a background in printing. In particular, I still		523	for someone without a background in printing. In particular, I still
	616	haven't got to grips with fine control of page-breaking logic, and		524	haven't got to grips with fine control of page-breaking logic, and
	617	have to hope noone minds too much about tables which split awkwardly		525	have to hope noone minds too much about tables which split awkwardly
	618	over pages.		526	over pages.
	619			527
	620	[endsect]		528	[endsect]
	621			529
	622	[endsect]		530	[endsect]
	623			531
	624	[section DocBook in Action]		532	[section DocBook in Action]
	625			533
	626	[section The Rush to Completion]		534	[section The Rush to Completion]
	627			535
	628	In the end, though, all went better than we could have hoped.		536	In the end, though, all went better than we could have hoped.
	629			537
	630	I soon had the documentation build integrated with the Product		538	I soon had the documentation build integrated with the Product
	631	build. Now the distributable ISO CD image had the right version of the		539	build. Now the distributable ISO CD image had the right version of the
	632	User Manual automatically included.		540	User Manual automatically included.
	633			541
n	634	I wrote a script to check the integration between the Product and the	n	542	I wrote a simple program to check the integration between the Product
	635	User Manual. This script double-checked that the various page/anchor		543	and the User Manual. This program checked that the various page/anchor
	636	targets which the Product used to launch the pop up Help window were		544	targets which the Product used to launch the pop up Help window were
	637	valid. This script too became part of the build. It provided a		545	valid. This script too became part of the build. It provided a
	638	rudimentary safety net as I rolled in more and more content.		546	rudimentary safety net as I rolled in more and more content.
	639			547
	640	Next, I cannibalised the good bits of the existing manual. We knew		548	Next, I cannibalised the good bits of the existing manual. We knew
	641	what problems we had seen in the field: some could be fixed using		549	what problems we had seen in the field: some could be fixed using
	642	better examples in the Help text; I fixed these next.		550	better examples in the Help text; I fixed these next.
	643			551
	644	Within a couple of days the new manual had all the good content from		552	Within a couple of days the new manual had all the good content from
	645	the old manual and none of the misleading or inaccurate content; it		553	the old manual and none of the misleading or inaccurate content; it
	646	included some new sections and was fully linked to the Product. It		554	included some new sections and was fully linked to the Product. It
	647	was, though, very light on screen shots.		555	was, though, very light on screen shots.
	648			556
	649	[endsect]		557	[endsect]
	650			558
	651	[section Screen Captures]		559	[section Screen Captures]
	652			560
	653	In an ideal world we could programatically:		561	In an ideal world we could programatically:
	654			562
	655	* launch the Product;		563	* launch the Product;
	656	* load some data;		564	* load some data;
	657	* pose the user interface for a number of screen shots;		565	* pose the user interface for a number of screen shots;
	658	* capture these screen shots for inclusion in the documentation.		566	* capture these screen shots for inclusion in the documentation.
	659			567
	660	Then this program too could become part of the build and, in theory,		568	Then this program too could become part of the build and, in theory,
	661	the screen shots would never fall out of step with the Product.		569	the screen shots would never fall out of step with the Product.
	662			570
	663	Already we had some tools in place to automate data loading and to		571	Already we had some tools in place to automate data loading and to
	664	exercise the user interface. We still have no solution for		572	exercise the user interface. We still have no solution for
	665	automatically capturing and cropping the images, so we rely on		573	automatically capturing and cropping the images, so we rely on
	666	human intervention. So far, this hasn't been a huge issue.		574	human intervention. So far, this hasn't been a huge issue.
	667			575
	668	[endsect]		576	[endsect]
	669			577
	670	[section QuickBook]		578	[section QuickBook]
	671			579
	672	I had a workaround for the verbosity issue. I used QuickBook, one of		580	I had a workaround for the verbosity issue. I used QuickBook, one of
	673	the __boost__ tools. QuickBook is a lightweight C++ program which		581	the __boost__ tools. QuickBook is a lightweight C++ program which
n	674	generates DocBook (BoostBook, strictly speaking) XML from a WikiWiki	n	582	generates DocBook XML from a WikiWiki style source document.
	675	style source document.
	676			583
	677	Using QuickBook, we can write our previous example as:		584	Using QuickBook, we can write our previous example as:
	678			585
n	679	[pre	n	586	[pre
	680	\[section Hello World\]		587	We needed just two output formats:
	681			588
n	682	Here is the canonical C++ example program.	n	589	* hard copy, printed and bound
	683			590	* linked online web pages.
	684	#include <iostream>
	685
	686	int main() {
	687	std::cout << "Hello world!" << std::endl;
	688	return 0;
	689	}
	690
	691	\[endsect\]
	692	]		591	]
	693			592
	694	QuickBook documents are easy to read and easy to write. QuickBook does		593	QuickBook documents are easy to read and easy to write. QuickBook does
	695	fall a long way short of the full expressive richness of DocBook but		594	fall a long way short of the full expressive richness of DocBook but
	696	if all you need are sections, cross-references, tables, lists,		595	if all you need are sections, cross-references, tables, lists,
n	697	embedded images and so on, then it's ideal.	n	596	embedded images and so on, then it's ideal.
	698	This [@softdoc.qbk master version] of this article is itself written
	699	in QuickBook.
	700
	701	You can even escape back to DocBook from QuickBook. So if you decide
	702	your manual needs, for example, a
	703	[@http://docbook.org/tdg/en/html/colophon-x.html colophon], you can do
	704	it!
	705			597
	706	[endsect]		598	[endsect]
	707			599
	708	[section Build Times]		600	[section Build Times]
	709			601
	710	It wasn't going to be hard to beat Word Doctor on build		602	It wasn't going to be hard to beat Word Doctor on build
	711	times. Currently, it takes about a minute to generate the full user		603	times. Currently, it takes about a minute to generate the full user
n	712	manual, in PDF and HTML format, from source. A simple dependency check	n	604	manual, in both PDF and HTML formats, from source. A simple dependency
	713	means this build is only triggered when required. The real gain here		605	check means this build is only triggered when required. The real gain
	714	is not so much that the build is quick, but that it is automatic: not		606	here is not so much that the build is quick, but that it is automatic:
	715	a single button needs clicking.		607	not a single button needs clicking.
	716			608
	717	[endsect]		609	[endsect]
	718			610
	719	[endsect]		611	[endsect]
	720			612
	721	[section Soft Documentation]		613	[section Soft Documentation]
	722			614
	723	As a software user I expect software to just work---especially		615	As a software user I expect software to just work---especially
	724	software with a GUI. It should be obvious what to do without needing		616	software with a GUI. It should be obvious what to do without needing
	725	to read the manual; and preferably without even waiting for tooltips		617	to read the manual; and preferably without even waiting for tooltips
	726	to float into view. By designing a GUI which operates within a web		618	to float into view. By designing a GUI which operates within a web
	727	browser we already have a headstart here: the user interface is driven		619	browser we already have a headstart here: the user interface is driven
	728	like any other web interface---there's no need to document how		620	like any other web interface---there's no need to document how
	729	hyperlinks work or what the browser's address bar does.		621	hyperlinks work or what the browser's address bar does.
	730			622
	731	What's more, the [@http://agilemanifesto.org/		623	What's more, the [@http://agilemanifesto.org/
	732	Manifesto for Agile Software Development] explicitly		624	Manifesto for Agile Software Development] explicitly
	733	prefers: "Working software over comprehensive documentation".		625	prefers: "Working software over comprehensive documentation".
	734			626
	735	These considerations don't mean that the manual is redundant or		627	These considerations don't mean that the manual is redundant or
	736	unwanted, though. There are times when we don't want to clutter the		628	unwanted, though. There are times when we don't want to clutter the
	737	core user interface with reference details. There remain occasions		629	core user interface with reference details. There remain occasions
	738	when hardcopy is invaluable.		630	when hardcopy is invaluable.
	739			631
	740	What's more, when you try and design an intuitive user interface, you		632	What's more, when you try and design an intuitive user interface, you
	741	realise that the distinction between software and documentation is		633	realise that the distinction between software and documentation is
	742	somewhat artificial: it's not so much that the boundaries blur as		634	somewhat artificial: it's not so much that the boundaries blur as
	743	that, from a user's point of view, they aren't really there. Suppose,		635	that, from a user's point of view, they aren't really there. Suppose,
	744	for example, that a form requires an email address to be entered. If		636	for example, that a form requires an email address to be entered. If
	745	the user enters an invalid address the form is redrawn with the		637	the user enters an invalid address the form is redrawn with the
	746	erroneous input highlighted and a terse message displayed: ['Please		638	erroneous input highlighted and a terse message displayed: ['Please
	747	enter a valid email address]; there will also be a clickable Help icon		639	enter a valid email address]; there will also be a clickable Help icon
	748	directing confused users to the right page of the user manual. Which		640	directing confused users to the right page of the user manual. Which
	749	of these elements of the user interface are software and which are		641	of these elements of the user interface are software and which are
	750	documentation?		642	documentation?
	751			643
	752	Now suppose we are delivering a library designed to be linked into a		644	Now suppose we are delivering a library designed to be linked into a
	753	larger program. The documentation is primarily the header files which		645	larger program. The documentation is primarily the header files which
	754	define the interface to this library. We must invest considerable		646	define the interface to this library. We must invest considerable
	755	effort making sure these header files define a coherent and		647	effort making sure these header files define a coherent and
	756	comprehensible interface: maybe we deliver the library with some		648	comprehensible interface: maybe we deliver the library with some
	757	example client code and makefiles; maybe we provide a test harness;		649	example client code and makefiles; maybe we provide a test harness;
	758	maybe we generate hyperlinked documentation directly from the source		650	maybe we generate hyperlinked documentation directly from the source
	759	files; and maybe we supply the library implementation as source		651	files; and maybe we supply the library implementation as source
	760	code. Now which is software and which is documentation?		652	code. Now which is software and which is documentation?
	761			653
	762	When we write software, we remember		654	When we write software, we remember
	763	[link refs.abelson_and_sussman Abelson and Sussman's] advice:		655	[link refs.abelson_and_sussman Abelson and Sussman's] advice:
	764			656
	765	[:Programs should be written for people to read, and only incidentally		657	[:Programs should be written for people to read, and only incidentally
	766	for machines to execute.]		658	for machines to execute.]
	767			659
	768	In other words, software is documentation. Software should also be		660	In other words, software is documentation. Software should also be
	769	soft---soft enough to adapt to changing requirements. We must be sure		661	soft---soft enough to adapt to changing requirements. We must be sure
	770	to keep our documentation soft too.		662	to keep our documentation soft too.
	771			663
	772	[endsect]		664	[endsect]
	773			665
n			n	666
	774	[section Conclusions]		667	[section Conclusions]
	775			668
n	776	The real benefits of the new documentation toolchain are becoming more	n	669	The real benefits of the new documentation toolchain are becoming more a
				>	nd
	777	and more apparent.		670	more apparent.
	778			671
	779	As a simple example, a single text file defines the Product's four		672	As a simple example, a single text file defines the Product's four
	780	part version number. The build system processes this file to make sure		673	part version number. The build system processes this file to make sure
	781	the correct version number appears where it's needed: in the user		674	the correct version number appears where it's needed: in the user
	782	interface, in the CD install script---and, of course, in the		675	interface, in the CD install script---and, of course, in the
	783	documentation.		676	documentation.
	784			677
	785	Another example. If we get a support call which we think could have		678	Another example. If we get a support call which we think could have
	786	been avoided had the documentation been better, then we fix the		679	been avoided had the documentation been better, then we fix the
n	787	documentation directly. Anyone with access to the revision control	n	680	documentation directly. Anyone with access to the version control
	788	system and a text editor can make the fix. The full printed and online		681	system and a text editor can make the fix. The full printed and online
	789	documentation will be regenerated when they next do a build, and will		682	documentation will be regenerated when they next do a build, and will
	790	automatically be included in the next release.		683	automatically be included in the next release.
	791			684
	792	And a final example. The Product I work on checks file-based digital		685	And a final example. The Product I work on checks file-based digital
	793	video: it can spot unpleasant compression artifacts, unwanted black		686	video: it can spot unpleasant compression artifacts, unwanted black
	794	frames, audio glitches and so on. The range and depth of these checks		687	frames, audio glitches and so on. The range and depth of these checks
	795	is perhaps the area which changes most frequently: when we add support		688	is perhaps the area which changes most frequently: when we add support
n	796	for a new video codec or container file format, for example. The	n	689	for a new video standard, for example. The architecture we have in
	797	architecture we have in place means that these low level enhancements		690	place means that these low level enhancements disrupt the higher
	798	disrupt the higher levels of the software only minimally: in fact, the		691	levels of the software only minimally: in fact, the user interface for
	799	user interface for this part of the Product is dynamically generated		692	this part of the Product is dynamically generated from a formal
	800	from a formal description of the supported checks. Adding a check at		693	description of which checks are supported. Adding a check at this
	801	this level is a simple matter of extending this formal description. We		694	level is a simple matter of extending this formal description. We also
	802	also need to document the check: perhaps a reference to the codec		695	need to document the check: perhaps a reference to the video standard
	803	specification and a precise definition of the metrics used. With an		696	and a precise definition of the metrics used. With an intelligent
	804	intelligent documentation toolchain the documentation can live		697	documentation toolchain the documentation can live alongside the
	805	alongside the formal description and build time checks confirm the		698	formal description and build time checks confirm the help text links
	806	help text links up properly.		699	up properly.
	807			700
	808	From an engineering point of view, documentation is properly		701	From an engineering point of view, documentation is properly
	809	integrated into the Product. I finish with another quotation from		702	integrated into the Product. I finish with another quotation from
	810	[@http://www.sagehill.net/docbookxsl/index.html Stayton]:		703	[@http://www.sagehill.net/docbookxsl/index.html Stayton]:
	811			704
	812	[:Setting up a DocBook system will take some time and effort. But the		705	[:Setting up a DocBook system will take some time and effort. But the
n	813	payoff will be an efficient, flexible, and inexpensive publishing	n	706	payoff will be an efficient, flexible, and inexpensive publishing system
	814	system that can grow with your needs.]		707	that can grow with your needs.]
	815			708
	816	[endsect]		709	[endsect]
	817			710
	818	[section:refs References]		711	[section:refs References]
	819			712
	820	[h3 Abelson and Sussman]		713	[h3 Abelson and Sussman]
	821			714
	822	['Structure and Interpretation of Computer Progams],		715	['Structure and Interpretation of Computer Progams],
	823	Harold Abelson, Gerald Jay Sussman with Julie Sussman,		716	Harold Abelson, Gerald Jay Sussman with Julie Sussman,
	824	MIT Press, 1984; ISBN 0-262-01077-1		717	MIT Press, 1984; ISBN 0-262-01077-1
	825			718
	826	[h3 Apache FOP]		719	[h3 Apache FOP]
	827			720
	828	[@http://xmlgraphics.apache.org/fop/]		721	[@http://xmlgraphics.apache.org/fop/]
	829			722
	830	[h3 Agile Manifesto]		723	[h3 Agile Manifesto]
	831			724
	832	Manifesto for Agile Software Development\n		725	Manifesto for Agile Software Development\n
	833	[@http://agilemanifesto.org/]		726	[@http://agilemanifesto.org/]
	834			727
	835	[h3 Boost]		728	[h3 Boost]
	836			729
	837	[@http://www.boost.org/]		730	[@http://www.boost.org/]
	838			731
	839	[h3 BoostBook]		732	[h3 BoostBook]
	840			733
	841	[@http://www.boost.org/tools/boostbook/]		734	[@http://www.boost.org/tools/boostbook/]
	842			735
	843	[h3 Boost QuickBook]		736	[h3 Boost QuickBook]
	844			737
	845	[@http://www.boost.org/tools/quickbook/]		738	[@http://www.boost.org/tools/quickbook/]
	846			739
	847	[h3 DocBook]		740	[h3 DocBook]
	848			741
	849	[@http://docbook.org]		742	[@http://docbook.org]
	850			743
n	851	[h3 Hibernate]	n
	852
	853	[@http://www.hibernate.org/]
	854
	855	[h3 Microsoft Word]		744	[h3 Microsoft Word]
	856			745
	857	[@http://office.microsoft.com/]		746	[@http://office.microsoft.com/]
	858			747
	859	[h3 Stayton]		748	[h3 Stayton]
	860			749
	861	['DocBook XSL: The Complete Guide],		750	['DocBook XSL: The Complete Guide],
	862	[@http://www.sagehill.net/docbookxsl/index.html]		751	[@http://www.sagehill.net/docbookxsl/index.html]
	863			752
	864	[h3 The DocBook Project]		753	[h3 The DocBook Project]
	865			754
	866	[@http://docbook.sourceforge.net/]		755	[@http://docbook.sourceforge.net/]
	867			756
	868	[endsect]		757	[endsect]
	869			758
	870	[section Credits]		759	[section Credits]
	871			760
n	872	My thanks to Alan Griffiths, Phil Bass and Alison Peck for their help	n	761	My thanks to the editorial teams at both Overload and Communicator
	873	with this article.		762	for their help with this article.
	874			763
	875	[endsect]		764	[endsect]
	876			765
n	877	[section Colophon]	n
	878			766
n	879	[@softdoc_overload.qbk The master version of this article] was written	n
	880	in QuickBook format using emacs. This online edition has been created
	881	using the QuickBook, BoostBook, DocBook and xsltproc tools.
	882			767
t	883	[endsect]	t

Legends
Colors  Added  Changed Deleted	Links (f)irst change (n)ext change (t)op