Does anybody here know anything about Adobe InDesign?

Our product manual is produced with it. The manual has always been the 
most neglected part of our product, so some while ago, management got 
the Graphics department to redo the manual. And by "redo", I mean "make 
it look like a glossy magazine".

The manual is very, very pretty. I can't even explain it in words 
properly. I can't put my finger on *what* exactly is so good about it, 
but it just *looks professional*. It looks really slick. I could have 
wasted hundreds of hours buggering around with formatting commands and 
still not come up with anything remotely this good-looking.

I guess that's what happens when you pay professional graphic artists to 
make your stuff look good!

The trouble is... the actual *content* of the manual is awful. (The 
Graphics department only changed the formatting, not the content.) Half 
of it is three point-releases out of date. There are new features that 
aren't explained anywhere. The manual is huge and intimidating, and very 
poorly organised. The English is poor in many places. Some irrelevant 
things are explained in unnecessary detail, while other important 
information is barely explained at all. In short, it sucks.

We all know it sucks. But it would take a long time for somebody to 
write something better. And there's people banging on the door wanting 
new software features, so...

Anyway, I don't think anybody here actually knows how to *use* InDesign. 
Oh, various people have got it to "work", but I don't think any of us 
know how to use it properly. The Graphics department have built a 
document that looks beautiful, but it's intractably difficult to 
*change* anything. The table of contents was produced by hand (I can 
tell from the inconsistent typos), the running titles on the pages were 
produced by hand, all the cross-references were done manually (several 
of them are incorrect), and so on. It appears that to add a new page, 
you basically copy-paste an existing page and then edit the contents to 
make it different. (And then go edit the page numbers on all the 
succeeding pages.)

What we *really* want to do is put the manual into source control. 
But... well, putting a binary blob into source control doesn't really 
help much. You *can* put a Word document into source control, but it's 
impossible to tell what got changed on each commit, so why bother?

What we actually want to do is write some sort of "source code" which 
contains the textual content of the manual and some markup instructions, 
and then press a button somewhere, and have a glossy magazine drop out 
the other end. Can InDesign do that? Or do we need to find another tool?

(We could use LaTeX - but it makes your document look like a stuffy 
academic publication rather than a trendy commercial product brochure. 
I've been looking into DocBook, but the PDF output looks *awful*! Like, 
even MS Word looks less chunky than this stuff! Perhaps we could use a 
custom XML schema and I could code up some suitable XSLT for it... but I 
very much doubt that my coding skills can match the talent of 
professional graphics designers.)

Everything I've managed to read about InDesign (i.e., not much) says 
it's brilliant for producing posters and flyers. E.g., the product page 
talks about "pixel perfect" design - which is what you want if you're 
designing one poster, once. But I'm not seeing anything about 
automatically processing big chunks of existing text into a pretty 
document. Maybe it can't do that...

Post a reply to this message

I know some people who could answer some of your questions, at least 
they can work with InDesign.
For the source control part...
Both .docx and .odt are in fact zip containers that contain the images 
and the content in different files. In theory you could extract the 
content part, put that under revision control. Check out the content, 
change, check in and rebuild the zipfile. Plus some manual fixing, but 
that would be minimal. If InDesign has the same sort of filestructure 
you might give that a try. Alternatively, many programs nowadays support 
version control. Did you check if InDesign does?


On 14-6-2014 13:42, Orchid Win7 v1 wrote:
> Does anybody here know anything about Adobe InDesign?
>
> Our product manual is produced with it. The manual has always been the
> most neglected part of our product, so some while ago, management got
> the Graphics department to redo the manual. And by "redo", I mean "make
> it look like a glossy magazine".
>
> The manual is very, very pretty. I can't even explain it in words
> properly. I can't put my finger on *what* exactly is so good about it,
> but it just *looks professional*. It looks really slick. I could have
> wasted hundreds of hours buggering around with formatting commands and
> still not come up with anything remotely this good-looking.
>
> I guess that's what happens when you pay professional graphic artists to
> make your stuff look good!
>
> The trouble is... the actual *content* of the manual is awful. (The
> Graphics department only changed the formatting, not the content.) Half
> of it is three point-releases out of date. There are new features that
> aren't explained anywhere. The manual is huge and intimidating, and very
> poorly organised. The English is poor in many places. Some irrelevant
> things are explained in unnecessary detail, while other important
> information is barely explained at all. In short, it sucks.
>
> We all know it sucks. But it would take a long time for somebody to
> write something better. And there's people banging on the door wanting
> new software features, so...
>
> Anyway, I don't think anybody here actually knows how to *use* InDesign.
> Oh, various people have got it to "work", but I don't think any of us
> know how to use it properly. The Graphics department have built a
> document that looks beautiful, but it's intractably difficult to
> *change* anything. The table of contents was produced by hand (I can
> tell from the inconsistent typos), the running titles on the pages were
> produced by hand, all the cross-references were done manually (several
> of them are incorrect), and so on. It appears that to add a new page,
> you basically copy-paste an existing page and then edit the contents to
> make it different. (And then go edit the page numbers on all the
> succeeding pages.)
>
> What we *really* want to do is put the manual into source control.
> But... well, putting a binary blob into source control doesn't really
> help much. You *can* put a Word document into source control, but it's
> impossible to tell what got changed on each commit, so why bother?
>
> What we actually want to do is write some sort of "source code" which
> contains the textual content of the manual and some markup instructions,
> and then press a button somewhere, and have a glossy magazine drop out
> the other end. Can InDesign do that? Or do we need to find another tool?
>
> (We could use LaTeX - but it makes your document look like a stuffy
> academic publication rather than a trendy commercial product brochure.
> I've been looking into DocBook, but the PDF output looks *awful*! Like,
> even MS Word looks less chunky than this stuff! Perhaps we could use a
> custom XML schema and I could code up some suitable XSLT for it... but I
> very much doubt that my coding skills can match the talent of
> professional graphics designers.)
>
> Everything I've managed to read about InDesign (i.e., not much) says
> it's brilliant for producing posters and flyers. E.g., the product page
> talks about "pixel perfect" design - which is what you want if you're
> designing one poster, once. But I'm not seeing anything about
> automatically processing big chunks of existing text into a pretty
> document. Maybe it can't do that...


-- 
Everytime the IT department forbids something that a researcher deems
necessary for her work there will be another hole in the firewall.

Post a reply to this message

On 14/06/2014 04:51 PM, andrel wrote:
> For the source control part...
> Both .docx and .odt are in fact zip containers that contain the images
> and the content in different files. In theory you could extract the
> content part, put that under revision control.

Yeah, but that probably won't work well in practice.

For example, we use a system called SpecFlow where you write integration 
tests in psuedo-English, and an external DLL transforms that into C# 
code. Both the source and the generated C# code are in source control. 
But the trouble is, if you insert or remove a single line in the 
SpecFlow file, the *entire* C# file changes. (Every line of the 
generated file is annotated with the corresponding line number in the 
SpecFlow file.)

I rather suspect that when you save an ODF file, the editor rebuilds the 
entire file and it won't look anything like what it did before. (I 
haven't tried, but I suspect that's what'll happen.) The other problem, 
of course, is that it's hard to make really polished ODF files in the 
first place. ;-)

> Alternatively, many programs nowadays support
> version control. Did you check if InDesign does?

As I say, nobody here seems to know how to work InDesign. It wouldn't 
surprise me if our current workflow can be significantly improved just 
by changing how the document it set up...

Post a reply to this message

On Sat, 14 Jun 2014 12:42:55 +0100, Orchid Win7 v1 wrote:

> Does anybody here know anything about Adobe InDesign?

Not specifically about InDesign - but FrameMaker isn't that different 
from it, I hear - and both products have a pretty steep learning curve 
that - once you know how the product works - actually ends up making 
sense.  Kind of like the first few releases of Blender after it was made 
an open source project (it had been a commercial product prior to that).

From Adobe's suite, FrameMaker is the tool of choice for producing 
documentation.  There are other products out there, but Adobe is pretty 
well entrenched - but that seems to be changing.  I know a few companies 
that use a product called Madcap Flare who really like it, but DITA is 
also becoming a lot more popular for information structuring and 
documentation.  It's a format rather than a tool, but there are some good 
tools for creating DITA (including, I understand, FrameMaker 12 - Frame 
11 isn't so good with it, though - but it can read and write DITA files).

As it happens, what I'm doing right now is a lot of this type of 
documentation work.  The client I'm working with right now has a mix of 
tools used for writing and publishing the documentation, but the 
direction is to simplify this because production is way too complicated 
and has too many moving parts from different vendors.

Take a look at DITA tools - I'm going to start looking at oXygen (an 
editor - well, an IDE) fairly soon.  One of the client's products is 
documented using DITA, and the guy who handles it seems to have a very 
good workflow.  oXygen can produce PDFs, XHTML, or pretty much whatever 
sort of output you want.

But a tool alone isn't (hopefully obviously) going to give you great 
documentation.  You also need technical writers (at least one).

A good technical writer isn't akin to "Tina the Tech Writer" in Dilbert, 
but rather is someone who can learn and understand the product being 
documented, and can not only write about it, but can become an expert in 
using it *in order to write about it*.

Using DITA - which is an XML standard - means that putting the files in a 
source control management system works the way you'd expect.  I've done 
FrameMaker with various SCM tools, and while you don't get diffs, the 
version control is helpful.  But doing it in DITA means you can have some 
of those additional benefits.

The nice thing about using an XML standard like DITA is that you can use 
xslt to transform it, so if you need to customise the transformation, 
it's trivial to do - if you know xslt.

Jim

-- 
"I learned long ago, never to wrestle with a pig. You get dirty, and 
besides, the pig likes it." - George Bernard Shaw

Post a reply to this message

On 14-6-2014 19:39, Orchid Win7 v1 wrote:
> On 14/06/2014 04:51 PM, andrel wrote:
>> For the source control part...
>> Both .docx and .odt are in fact zip containers that contain the images
>> and the content in different files. In theory you could extract the
>> content part, put that under revision control.
>
> Yeah, but that probably won't work well in practice.
>
> For example, we use a system called SpecFlow where you write integration
> tests in psuedo-English, and an external DLL transforms that into C#
> code. Both the source and the generated C# code are in source control.
> But the trouble is, if you insert or remove a single line in the
> SpecFlow file, the *entire* C# file changes. (Every line of the
> generated file is annotated with the corresponding line number in the
> SpecFlow file.)
>
> I rather suspect that when you save an ODF file, the editor rebuilds the
> entire file and it won't look anything like what it did before. (I
> haven't tried, but I suspect that's what'll happen.) The other problem,
> of course, is that it's hard to make really polished ODF files in the
> first place. ;-)


it is clear that you haven't checked ;)
I made a little document saved it as .odt and opened it as .zip.
In it is the content.xml file that after a lot of presumable 
initialization contains (I added some newlines):

--------contents.xml---------------
.
.
.

<text:h text:style-name="Heading_20_1" text:outline-level="1">This is a 
file for andy</text:h><text:p text:style-name="Text_20_body"/>

<text:p text:style-name="Text_20_body">Add a mascot below</text:p>

<text:p text:style-name="Text_20_body">
<draw:frame draw:style-name="fr1" draw:name="graphics1" 
text:anchor-type="as-char" svg:width="5.292cm" svg:height="8.255cm" 
draw:z-index="0">
<draw:image 
xlink:href="http://upload.wikimedia.org/wikipedia/commons/thumb/5/5b/RoyalRegimentWalesGoat_gobeirne.jpg/200px-RoyalRegimentWalesGoat_gobeirne.jpg"

xlink:type="simple" xlink:show="embed" xlink:actuate="onLoad"/>
</draw:frame>
</text:p>

<text:p text:style-name="Text_20_body">see, it is above </text:p>
.
.
.
-----------end contents.xml------------

Easy enough to understand, to modify and to repackage. The image was 
added as a link. If you add it to the document it will be in a directory 
local to the zip file.


-- 
Everytime the IT department forbids something that a researcher deems
necessary for her work there will be another hole in the firewall.

Post a reply to this message

> But a tool alone isn't (hopefully obviously) going to give you great
> documentation.  You also need technical writers (at least one).

I'd like to take a stab at this myself. I believe I'm quite a good 
writer. The question, of course, is whether I can find the time to do this.

Trouble is, currently the documentation sucks, but nobody has the time 
to produce something better, so we're just doing minor tweaks to it 
whenever the product changes. Really the entire thing wants to be thrown 
in the bin and somebody to start again. But if I turn up and go "hey, 
here's the new manual" and it's *not* as shiny and pretty to look at as 
the old one... nobody tell take any notice.

> The nice thing about using an XML standard like DITA is that you can use
> xslt to transform it, so if you need to customise the transformation,
> it's trivial to do - if you know xslt.

DocBook is an XML standard. So - in theory - it's "trivial" to make it 
do what you want.

...in reality, I found it hellishly difficult to change even the tiniest 
detail about it. Perhaps it would be simpler to rewrite the XSLT from 
scratch rather than try to figure out how it works. And maybe, just 
maybe, the XML-FO processor I'm using just can't be convinced to produce 
nice output.

For that matter, we could write documentation in HTML and apply lashings 
of CSS to it. You can do paper-specific CSS settings and so forth, and 
everybody in the room already knows how CSS and HTML work. Again, the 
trouble is, you'll never get it to look slick and polished.

Post a reply to this message

> The other problem,
> of course, is that it's hard to make really polished ODF files in the
> first place. ;-)
>

No it's not.  It only requires a bit of planning, and military 
enforcement of the rules, if you have multiple editors.

>> Alternatively, many programs nowadays support
>> version control. Did you check if InDesign does?
>
> As I say, nobody here seems to know how to work InDesign. It wouldn't
> surprise me if our current workflow can be significantly improved just
> by changing how the document it set up...

Yes.

I don't know InDesign, but I knew a few of its ancestors.

Just as CSS with HTML, or a complex software program, you need a plan 
and _you need to stick to it_.

- Define styles (ex: title, subtitles, section heading, text, code, 
examples,etc...) *AND USE TO THEM*  No more "I know the subtitle is 
Arial 14 pts, bold, so I'll manually change the properties of that 
sentence."
- Create page templates (left side should look like this, right side 
should look like that, first page of a chapter should look like that, 
etc...)
- Put section titles macros in the headers, and page number macros in 
the footers.
- Generate the table of contents automatically.
- Put someone in charge of maintaining the manual.  He or she can (and 
should) accept input from the rest of the team, but he or she has the 
last word on the format.
- That someone should have a backup, in case of vacations or wild bus 
rampage.

Tada!

Whether you use WordPerfect 5.1, vi and LaTex, emacs, Office365, or the 
latest Adobe Creative Suite, the above rules will have your manual at 
least look decent.

-- 
/*Francois Labreque*/#local a=x+y;#local b=x+a;#local c=a+b;#macro P(F//
/*    flabreque    */L)polygon{5,F,F+z,L+z,L,F pigment{rgb 9}}#end union
/*        @        */{P(0,a)P(a,b)P(b,c)P(2*a,2*b)P(2*b,b+c)P(b+c,<2,3>)
/*   gmail.com     */}camera{orthographic location<6,1.25,-6>look_at a }

Post a reply to this message

Le 2014-06-14 17:38, Orchid Win7 v1 a écrit :
>> But a tool alone isn't (hopefully obviously) going to give you great
>> documentation.  You also need technical writers (at least one).
>
> I'd like to take a stab at this myself. I believe I'm quite a good
> writer. The question, of course, is whether I can find the time to do this.
>
> Trouble is, currently the documentation sucks, but nobody has the time
> to produce something better, so we're just doing minor tweaks to it
> whenever the product changes. Really the entire thing wants to be thrown
> in the bin and somebody to start again. But if I turn up and go "hey,
> here's the new manual" and it's *not* as shiny and pretty to look at as
> the old one... nobody tell take any notice.
>
>> The nice thing about using an XML standard like DITA is that you can use
>> xslt to transform it, so if you need to customise the transformation,
>> it's trivial to do - if you know xslt.
>
> DocBook is an XML standard. So - in theory - it's "trivial" to make it
> do what you want.
>
> ...in reality, I found it hellishly difficult to change even the tiniest
> detail about it. Perhaps it would be simpler to rewrite the XSLT from
> scratch rather than try to figure out how it works.

Right, because RTFMing is impossible...

> And maybe, just
> maybe, the XML-FO processor I'm using just can't be convinced to produce
> nice output.
>

Your problem, is that you do not like the default CSS used by your 
docbook editor, not that it can't be convinced to produce nice output.

The problem is not with the tool.  The problem is with what you're 
telling your tool to do (or not telling it to do).  As I said in my 
other response, any word processor younger than you is able to print 
crisp Arial 16pts or justify text properly.

If you want your manual to look good, you actually have to tell whatever 
tool you plan on using that you want it to look good.

You need to create page templates that look good.
You need to chose font combinations that are pleasing to the eye: 
sans-serif for titles, serif for text body, monospace for code or 
command line text.
UNDER NO CIRCUMSTANCE SHOULD YOU USE COMIC SANS.
You need to chose colors wisely.
Etc...

Of course, some software packages will make this easier to do than 
others, but regardless of your choice of software, noe of what you are 
trying to do is impossible, even for someone who doesn't have the artist 
gene, like you.

Your current manual looks impressive?  You like its look?  Then recreate 
the same thing with something you're familiar with, if you can't wrap 
your head around InDesign, or DocBook.

But the more important thing is - as you mention - the quality of the 
content.  Start by writing good content in Notepad (or vi, or gedit, or 
whatever) so that you can focus on the content.

Then import that text into some document formatting tool and apply the 
styles you have chosen to it.
-- 
/*Francois Labreque*/#local a=x+y;#local b=x+a;#local c=a+b;#macro P(F//
/*    flabreque    */L)polygon{5,F,F+z,L+z,L,F pigment{rgb 9}}#end union
/*        @        */{P(0,a)P(a,b)P(b,c)P(2*a,2*b)P(2*b,b+c)P(b+c,<2,3>)
/*   gmail.com     */}camera{orthographic location<6,1.25,-6>look_at a }

Post a reply to this message

On 16/06/14 14:26, Francois Labreque wrote:
> 
> But the more important thing is - as you mention - the quality of the
> content.  Start by writing good content in Notepad (or vi, or gedit, or
> whatever) so that you can focus on the content.
> 
> Then import that text into some document formatting tool and apply the
> styles you have chosen to it.

Excellent advice, Francois. Now the only problem is getting Andrew (and
others in the same position) to follow it.

John
-- 
Protect the Earth
It was not given to you by your parents
You hold it in trust for your children

Post a reply to this message

>> DocBook is an XML standard. So - in theory - it's "trivial" to make it
>> do what you want.
>>
>> ...in reality, I found it hellishly difficult to change even the tiniest
>> detail about it. Perhaps it would be simpler to rewrite the XSLT from
>> scratch rather than try to figure out how it works.
>
> Right, because RTFMing is impossible...

Most things to do with XML are hard. For whatever reason, XML is 
absurdly overcomplicated, considering what it actually does.

It took me hours of Google searching just to figure out how to make 
DocBook allow me to write character entities. (The manual says it works 
already... Oh, wait, that's for DocBook v4. OK, so how do you make it 
work for v5? Oh yeah, we removed that feature. Great, so how do I turn 
it back on?) I got there eventually, but it was a hell of a lot of work.

Similar fun with XInclude. The manual tells you that XInclude is a great 
way to make modular documents - and so much better than the old entity 
workaround we used to recommend you use. Except, you know what? My XML 
validator and my XSLT processor both POINT-BLANK INGORE any and all 
XInclude declarations. Isn't that wonderful?

>> And maybe, just
>> maybe, the XML-FO processor I'm using just can't be convinced to produce
>> nice output.
>
> Your problem, is that you do not like the default CSS used by your
> docbook editor, not that it can't be convinced to produce nice output.

I don't have a "DocBook editor", I have a text editor with a vague 
understanding of XML. And then I have various command-line tools which, 
after about a day of research, I was able to convince to produce PDF 
output. Fortunately, all of this knowledge can be embedded into scripts. ;-)

> The problem is not with the tool. The problem is with what you're
> telling your tool to do (or not telling it to do). As I said in my other
> response, any word processor younger than you is able to print crisp
> Arial 16pts or justify text properly.

Yes, but can it render the chapter titles in a blue box with rounded 
corners and a fuzzy drop-shadow? Probably not.

> Your current manual looks impressive? You like its look? Then recreate
> the same thing with something you're familiar with, if you can't wrap
> your head around InDesign, or DocBook.

As I say, I can't actually put my finger on exactly what it is about the 
current manual that makes it look so good. It probably isn't any one 
particular thing, it's the cumulative total of many, many small things...

> But the more important thing is - as you mention - the quality of the
> content. Start by writing good content in Notepad (or vi, or gedit, or
> whatever) so that you can focus on the content.
>
> Then import that text into some document formatting tool and apply the
> styles you have chosen to it.

Whilst I agree wholeheartedly, if we write a whole bunch of content as 
(say) TeX input and then decide that actually our tool of choice wants 
XML (or vice versa)...

That's kind of why I'd like to pin down exactly what tool we're going to 
use. Once we start the rewrite, I only want to do it once.

Still, I could sit down and look at the high-level document structure - 
that's very easy to change for any tool.

Post a reply to this message