 |
|
|
|
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Le 2014-06-14 13:39, Orchid Win7 v1 a écrit :
> 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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Le 2014-06-16 14:39, Orchid Win7 v1 a écrit :
>>> 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.
>
Convince your boss to buy you this:
http://shop.oreilly.com/product/9780596805012.do
But what's so complicated about:
<chapter>
<title>Lorem ipsum</title>
<para>dolor sit amet</para>
</Chapter>
There's also wiki.docbook.org, but it seems to be running on an ailing
386... I gave up waiting for it, just to rebuke someone on a newsgroup.
> 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.
http://www.docbook.org/docs/howto/#entities
http://www.docbook.org/docs/howto/#faq-authoring-general-entities
>
> 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?
>
Upgrade?
>>> 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.
> ;-)
http://www.docbook.org/docs/howto/#editors
>
>> 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.
>
The fuzzy drop shadow and rounded corners are not part of the CSS
specification (yet!), so it would require tinkering (ex: running the XML
through a preprocessor to convert every TITLE block into a table that
has specific images as a background), but it's not impossible.
For the rest:
//Andy.css
CHAPTER TITLE {
background-color: blue;
color: white;
font-family: Arial Verdana Sand-serif;
font-variant: small-caps;
font-weight: bold;
font-size: 24pt;
}
and then use that stylesheet when processing your .xml file.
>> 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)...
Which is why you shouldn't write it with ANY output format or tool in
mind. Think a big README.TXT
>
> 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.
While it's not a bad idea to have an idea of where you're going, it
shouldn't be your main consideration yet. You should focus on making
the documentation up to date, first.
>
> Still, I could sit down and look at the high-level document structure -
> that's very easy to change for any tool.
Yep.
--
/*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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>>>> 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.
>>
>
> Convince your boss to buy you this:
> http://shop.oreilly.com/product/9780596805012.do
I sorely doubt that any of that book will say anything whatsoever about
the toolchain problems I'm struggling with. It'll just be 500 pages
about the actual DocBook markup itself - which I'm having no problem with.
> But what's so complicated about:
>
> <chapter>
> <title>Lorem ipsum</title>
> <para>dolor sit amet</para>
> </Chapter>
OK, now go re-read what I actually said.
Writing the DocBook stuff itself is easy enough. (That's why I'm looking
at it in the first place.) Configuring the DocBook XSLT stuff is
difficult. Trying to make entities work is difficult. Trying to split
the file into parts is difficult. All the stuff that isn't to do with
writing the actual textual content just seems really difficult.
>> 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.
>
> http://www.docbook.org/docs/howto/#entities
This is about how to make XSLT not strip off custom entities that you
personally have defined (e.g., your product's name). It has nothing to
do with standard entities like .
> http://www.docbook.org/docs/howto/#faq-authoring-general-entities
This is the *actual* solution. Do you have *any idea* how many Google
searches it took me to find this exact page?? (Also, why does every
single webpage related to DocBook take five lifetimes to load?)
>> 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?
>
> Upgrade?
To what? I'm using the latest versions of the tools recommended from the
DocBook website! :-P
>>> 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.
>> ;-)
>
> http://www.docbook.org/docs/howto/#editors
OK, so... Emacs, oXygen (which is just a general XML editor) and a
couple of other XML editors. Doesn't really offer any meaningful
advantage over any other text editor. And really, this isn't the part
that's causing trouble in the first place.
>> Yes, but can it render the chapter titles in a blue box with rounded
>> corners and a fuzzy drop-shadow? Probably not.
>
> The fuzzy drop shadow and rounded corners are not part of the CSS
> specification (yet!)
Indeed. That's my point. A tool focused on flashy graphics will have all
these sorts of capabilities - possibly at the expense of making it
harder to update the content though. (I say *possibly* - I still haven't
got to the bottom of what InDesign's actual capabilities may or may not be.)
>> 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)...
>
> Which is why you shouldn't write it with ANY output format or tool in
> mind. Think a big README.TXT
Sure. But the final thing is going to need markup. And I don't really
want to take a huge document and completely redo it to insert that
markup. It's much easier to insert markup as you write the thing in the
first place...
>> Still, I could sit down and look at the high-level document structure -
>> that's very easy to change for any tool.
>
> Yep.
Well then that's something productive I can actually go work on.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On Sat, 14 Jun 2014 22:38:40 +0100, Orchid Win7 v1 wrote:
>> 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.
From what I've seen, that belief has a good foundation.
> The question, of course, is whether I can find the time to do
> this.
That is always a challenge when it's not part of the official duties.
> 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.
You might do a little research on "targeted documentation." The idea
behind this is to break documentation into procedures, concepts, and
reference material - something that DITA is actually designed around.
>> 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.
True.
> ...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.
It's "trivial" once you understand it, just like using InDesign,
FrameMaker, or Blender, though, it's got a learning curve, and it's not
something you're going to understand overnight.
> 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.
One of the nice things about working with DITA is that you can easily
transform it (with the right tools) to XHTML or HTML. You can also get a
really slick publication out of it, because it can easily be transformed
to a PDF or other e-Book format (I'm partial to EPUB myself, and if
you're generating HTML, EPUB isn't much of a stretch).
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Le 2014-06-16 17:25, Orchid Win7 v1 a écrit :
>>>>> 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.
>>>
>>
>> Convince your boss to buy you this:
>> http://shop.oreilly.com/product/9780596805012.do
>
> I sorely doubt that any of that book will say anything whatsoever about
> the toolchain problems I'm struggling with. It'll just be 500 pages
> about the actual DocBook markup itself - which I'm having no problem with.
>
Sorry. Linked the wrong book. This is the one you need.
http://www.sagehill.net/book-description.html
By the way, both books are available online for free:
http://www.docbook.org/tdg5/en/html/docbook.html
http://www.sagehill.net/docbookxsl/index.html
>> But what's so complicated about:
>>
>> <chapter>
>> <title>Lorem ipsum</title>
>> <para>dolor sit amet</para>
>> </Chapter>
>
> OK, now go re-read what I actually said.
>
> Writing the DocBook stuff itself is easy enough. (That's why I'm looking
> at it in the first place.) Configuring the DocBook XSLT stuff is
> difficult. Trying to make entities work is difficult. Trying to split
> the file into parts is difficult. All the stuff that isn't to do with
> writing the actual textual content just seems really difficult.
>
>>> 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.
>>
>> http://www.docbook.org/docs/howto/#entities
>
> This is about how to make XSLT not strip off custom entities that you
> personally have defined (e.g., your product's name). It has nothing to
> do with standard entities like .
>
Ok. i thought it had to do with not losing entities in a v4 doc when
upgrading to v5. I thought you were upgrading v4 documents to v5, not
using a v4 book to write v5 docs. Sorry.
>> http://www.docbook.org/docs/howto/#faq-authoring-general-entities
>
> This is the *actual* solution. Do you have *any idea* how many Google
> searches it took me to find this exact page?? (Also, why does every
> single webpage related to DocBook take five lifetimes to load?)
>
It took me one attempt.
google "docbook".
docbook.org seems promising...
Oh! they have a Documentation section...
Ah! There's a "Users migrating from v4 to v5 should read..." link.
Hey! They even mention entities...
Sometimes Google just shows you how to fish. It doesn't always serve
you grilled salmon with a mango chutney.
>>> 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?
>>
>> Upgrade?
>
> To what? I'm using the latest versions of the tools recommended from the
> DocBook website! :-P
>
So you're saying that the latest and greatest release of your tool has a
problem with this:
1 <book xmlns="http://docbook.org/ns/docbook"
2 xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0">
<title>My First Book</title>
4 <xi:include href="chap1.xml"/>
<xi:include href="chap2.xml"/>
6 <xi:include href="chap3.xml"/>
<xi:include href="appa.xml"/>
8 <xi:include href="appb.xml"/>
</book>
(actual example from chapter 2 of the aforementioned O'RLY book)
That XInclude page is dated 2 May 2005. I maintain my suggestion to
upgrade to something more recent...
>>>> 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.
>>> ;-)
>>
>> http://www.docbook.org/docs/howto/#editors
>
> OK, so... Emacs, oXygen (which is just a general XML editor) and a
> couple of other XML editors. Doesn't really offer any meaningful
> advantage over any other text editor. And really, this isn't the part
> that's causing trouble in the first place.
>
They have embedded XML validators, syntax highlighting, online help, etc...
>>> Yes, but can it render the chapter titles in a blue box with rounded
>>> corners and a fuzzy drop-shadow? Probably not.
>>
>> The fuzzy drop shadow and rounded corners are not part of the CSS
>> specification (yet!)
>
> Indeed. That's my point. A tool focused on flashy graphics will have all
> these sorts of capabilities - possibly at the expense of making it
> harder to update the content though. (I say *possibly* - I still haven't
> got to the bottom of what InDesign's actual capabilities may or may not
> be.)
>
You shouldn't have any problem updating the title of any chapter, while
having it retain its blue box with fuzzy drop shadows. you may,
however, have problems keeping section numbers in order, if you start
moving stuff around, as it looks as if people didn't know how to work
with the document (much like most people are horrible at working with
titles, subtitles, and bulleted lists in Word)
--
/*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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
According to a friend of mine that has used InDesign for some personal
projects, InDesign can export and import XML. That could mean that you
only have to create a template and then insert the documentation by
automatic search and replace. (I use the same technique to build simple
websites.)
Apparently InDesign even has scripting facilities, she has not used them
herself. She is not a programmer, but a child of the WYSIWYG point and
click generation. All in all it sounds to me as something that matches
your interests and abilities. Perhaps she can even help you a bit. She
has met people that use complex programs to do simple tasks before (i.e.
we have worked together for some time).
--
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 18/06/2014 08:40 PM, andrel wrote:
> According to a friend of mine that has used InDesign for some personal
> projects, InDesign can export and import XML. That could mean that you
> only have to create a template and then insert the documentation by
> automatic search and replace. (I use the same technique to build simple
> websites.)
> Apparently InDesign even has scripting facilities, she has not used them
> herself. She is not a programmer, but a child of the WYSIWYG point and
> click generation. All in all it sounds to me as something that matches
> your interests and abilities. Perhaps she can even help you a bit. She
> has met people that use complex programs to do simple tasks before (i.e.
> we have worked together for some time).
OK. Well that all sounds like something worth looking into.
(I overheard the guy who's working on the documentation the other day.
We was explaining - as if this is a really complex and novel idea - how
he's managed to configure InDesign in such a way that it *automatically*
updates the table of contents and the index when you change something.
As if this is a really sophisticated idea, rather than - you know -
something that EVERY half-decent document production system should be
able to do out-of-the-box...)
It sounds like with some suitable tinkering, we could probably get quite
a nice workflow with this thing.
I wonder if there's any official documentation for it online. I'll take
a look...
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Le 2014-06-18 16:57, Orchid Win7 v1 a écrit :
>
> I wonder if there's any official documentation for it online. I'll take
> a look...
https://helpx.adobe.com/ca/indesign.html
(You'll need to replace the "ca" bit of the URL...)
- Go to adobe.com
- Click on menu
- Click on the inDesign icon
- Click Learn & support
--
/*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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Orchid Win7 v1 <voi### [at] dev null> wrote:
> On 18/06/2014 08:40 PM, andrel wrote:
> > According to a friend of mine that has used InDesign for some personal
> > projects, InDesign can export and import XML. That could mean that you
> > only have to create a template and then insert the documentation by
> > automatic search and replace. (I use the same technique to build simple
> > websites.)
> > Apparently InDesign even has scripting facilities, she has not used them
> > herself. She is not a programmer, but a child of the WYSIWYG point and
> > click generation. All in all it sounds to me as something that matches
> > your interests and abilities. Perhaps she can even help you a bit. She
> > has met people that use complex programs to do simple tasks before (i.e.
> > we have worked together for some time).
>
> OK. Well that all sounds like something worth looking into.
>
> (I overheard the guy who's working on the documentation the other day.
> We was explaining - as if this is a really complex and novel idea - how
> he's managed to configure InDesign in such a way that it *automatically*
> updates the table of contents and the index when you change something.
> As if this is a really sophisticated idea, rather than - you know -
> something that EVERY half-decent document production system should be
> able to do out-of-the-box...)
>
> It sounds like with some suitable tinkering, we could probably get quite
> a nice workflow with this thing.
>
> I wonder if there's any official documentation for it online. I'll take
> a look...
Good idea. I have had to work with indesign files given by clients and I managed
to work with it. I wouldn't compare the learning curve to Blender at all,
InDesign is a lot easier.
Alternatively afaik SVG supports feathered dropshadows and rounded boxes. I
think SVG could be the future of design because it seems to support just about
everything needed for print and web.
-Nekar Xenos-
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Le 19/06/2014 07:43, Nekar Xenos a écrit :
> Alternatively afaik SVG supports feathered dropshadows and rounded boxes. I
> think SVG could be the future of design because it seems to support just about
> everything needed for print and web.
svg has even draft about multipage... which, with the ability to use CSS
at top of svg file, might or might not be a good thing.
In formating of the page, there is already the World vs North-America
(A4 vs US letter). Either you designed your template to only use the
common area, dropping the margin (width 210 vs 216 mm, height 297 vs 279
mm, so 6 mm & 18 mm of white..), or you didn't and the change of paper
becomes "interesting" (truncated text, or repaginated with references
becoming wrong...)
A document is more than a collection of pages.
And remember: your documents will be migrated to the new company logo
and charts when the bigger corporation buy your company... or resell
it... or change its visual identity, or want to explore a new market.
Better keep a strict separation between formatting and content. (your
diagrams & pictures might show the company logo, but it should not be
copied inside every of them, it should be part of the formatting data
that can be referenced by them). The company name as well as the product
name are also not part of the content.
--
Just because nobody complains does not mean all parachutes are perfect.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Le 2014-06-19 02:27, Le_Forgeron a écrit :
> Le 19/06/2014 07:43, Nekar Xenos a écrit :
>
>> Alternatively afaik SVG supports feathered dropshadows and rounded boxes. I
>> think SVG could be the future of design because it seems to support just about
>> everything needed for print and web.
>
>
> svg has even draft about multipage... which, with the ability to use CSS
> at top of svg file, might or might not be a good thing.
>
> In formating of the page, there is already the World vs North-America
> (A4 vs US letter). Either you designed your template to only use the
> common area, dropping the margin (width 210 vs 216 mm, height 297 vs 279
> mm, so 6 mm & 18 mm of white..), or you didn't and the change of paper
> becomes "interesting" (truncated text, or repaginated with references
> becoming wrong...)
>
> A document is more than a collection of pages.
>
> And remember: your documents will be migrated to the new company logo
> and charts when the bigger corporation buy your company... or resell
> it... or change its visual identity, or want to explore a new market.
>
> Better keep a strict separation between formatting and content. (your
> diagrams & pictures might show the company logo, but it should not be
> copied inside every of them, it should be part of the formatting data
> that can be referenced by them). The company name as well as the product
> name are also not part of the content.
>
>
This.
I happen to work with commercial software packages that were bought,
renamed, and merged multiple times... It makes life interesting when
looking for upgrade logs. I imagine documentation writers must be
having a field day.
--
/*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 19-6-2014 8:27, Le_Forgeron wrote:
> Le 19/06/2014 07:43, Nekar Xenos a écrit :
>
>> Alternatively afaik SVG supports feathered dropshadows and rounded boxes. I
>> think SVG could be the future of design because it seems to support just about
>> everything needed for print and web.
>
>
> svg has even draft about multipage... which, with the ability to use CSS
> at top of svg file, might or might not be a good thing.
>
> In formating of the page, there is already the World vs North-America
> (A4 vs US letter). Either you designed your template to only use the
> common area, dropping the margin (width 210 vs 216 mm, height 297 vs 279
> mm, so 6 mm & 18 mm of white..), or you didn't and the change of paper
> becomes "interesting" (truncated text, or repaginated with references
> becoming wrong...)
Huh, I though current paper sizes were IPad, IPad mini, IPhone,
1600x1200,1280x1024,..., and whatever the android phones/tablets use.
--
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 Thu, 19 Jun 2014 01:43:15 -0400, Nekar Xenos wrote:
> I wouldn't compare the learning curve to Blender
> at all, InDesign is a lot easier.
The idea in the comparison (on my part) was not to say that they're
equally difficult, but that the UI seems to get in the way (at least with
FrameMaker, I've no direct experience with InDesign) until you understand
the workflow that it's designed for. I've used a number of Adobe
products over the years, and have found that to be the case.
IOW, it's not about "this is more difficult than that" but that it is
important to learn the tool, and there is a learning curve before one
becomes familiar enough to be very productive.
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 19/06/2014 4:20 PM, andrel wrote:
>
> Huh, I though current paper sizes were IPad, IPad mini, IPhone,
> 1600x1200,1280x1024,..., and whatever the android phones/tablets use.
>
So cynical for one so young. ;-)
--
Regards
Stephen
I solemnly promise to kick the next angle, I see.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Jim Henderson <nos### [at] nospamcom> wrote:
> On Thu, 19
> IOW, it's not about "this is more difficult than that" but that it is
> important to learn the tool, and there is a learning curve before one
> becomes familiar enough to be very productive.
>
> Jim
>
True. It did take some time to figure things out.
The documentation and Google helped a lot
-Nekar Xenos-
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
|
|
