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