Re: [docbook-apps] Show off what you've done with Docbook

[Thomas Schraitle <tom_schr@web.de>]

Hi Gerad,

Am Sonntag, 13. September 2015, 07:36:12 schrieben Sie:
> 
> After all, you can either learn to code it by hand, or use an editor like
> Oxygen. Either way, you do need to know the possibilities of the language,
> to know the best way to mark-up your document, but that's not really a
> problem.

To some degree, I agree. :)

Of course, a writer should be aware of the (endless?) possibilities of 
DocBook, at least to some extent. Otherwise it wouldn't be possible to create 
consistent and user-friendly documents. Writers should know their tools.

Furthermore, a writer should receive some training or reading a tutorial 
before starting to work with DocBook. However, this is true for every new 
technology, so this is nothing special.

From my experience, people are a little bit scared at a first glance. When you 
train them how to work with it and show them the different possibilties, 
actually they begin to see the advantages and like DocBook.

 
> There are 2 problems that I suspect for many make the difference between
> using the product and not:
> 
> 1. The complexity of setting up an environment: Download stylesheets,
> download toolchain (which includes numerous choices), create a directory
> structure for your own document.

Yes, there are different paths to success (and failures ;). DocBook only 
definies the schema (be it DTD, RNG, ...), but not the workflow. How you get 
from DocBook to your end format is totally up to you. Of course, the "basic" 
workflow is dictated through XML validation and XSLT transformation. However, 
people has different needs and how they fit together can be complex.

You can consider this as DocBook's greatest weakness -- or it's greatest 
freedom.

On the other hand, this is nothing new and people from all over the world 
tried to tackle this problem. 
As an example, openSUSE contains the "daps" package. No need to download 
everything manually, just install it on a openSUSE machine and all is 
correctly set up on your system. Of course, you have to adhere to the daps 
workflow. If it is good or bad depends on your use case.

However, when you work with daps, then all you need to do is to read the Quick 
Start as an introducery material and play with some examples to get used to 
it. The package frees the writer from all the boring and difficult 
administrative stuff. Same applies to other tools.


> 2. The complexity of customizing the default look of the documents, which
> look OK, but don't look as good as they would need to be to be put in front
> of a client.

I see the default look as "readable" and just a start. Sure, if you care about 
layout and typography this isn't enough and you need to customize the 
stylesheets to your needs.

However, small customizations aren't as difficult as it seems. With setting a 
parameter from one to zero (or vice versa) you can have a big impact on the 
result.

For bigger corrections in your layout: yes, it would be helpful to know XSLT. 
To make it easier for inexperiences users, I've tried to collect some of the 
prominent questions and created recipes in cookbook style: 
http://doccookbook.sourceforge.net/html/en/index.html

Of course, I agree, if you want to implement a complete corporate look and 
feel, this is something which takes more knowledge, time, and effort.

For a small teams, this is either delegated to a dedicated person or 
outsourced. This is of course out of scope for a single person.

 
> There clearly was, and still remains a need for Docbook. If you are
> supporting a technical project, the language itself meets most, if not all
> of your requirements outside the box.
> 
> But when I see the examples that have been provided as a result of the
> original question, I see documents that range from amazing to pretty
> ordinary. This not only shows the strength of the platform, but also the
> weakness.

Hmn, I'm not sure if you can blame DocBook for this. If people don't customize 
the result (for whatever reason) this isn't the fault of DocBook or the 
stylesheets. As I've wrote above, small customizations can be done through 
setting parameters. 


> As a Docbook user, and advocate, the amazing documents antagonize me the
> most, because I'm not sure I have the time and the will to understand how
> they were created.

If you do not have the time nor the will to create a corporate layout, then 
hire someone who has this abilitiy. ;)

 
> The question remains unanswered, having learned the Docbook language, why
> should somebody then have to face a much greater challenge to produce a
> document that looks presentable?

Maybe we should decide here if we are talk about ordinary, single users or 
teams who use DocBook.

I guess, some users are just satisfied with the result, don't know, or don't 
care. Only a few go the extra mile to customize stylesheets because they need 
it.

Regarding teams, I assume, they discussed the pros and cons and at some point 
they came to a decision. If their needs meet DocBook's portfolio why shouldn't 
they take the challenge? In most cases the problem solver is money: hire a 
dedicated XSLT engineer and you have it. ;)

 
> Does anybody sell a commercial Docbook customization layer? If this was
> Joomla, or Wordpress, or MediaWiki there would be a whole marketplace of
> free and commercial presentation layers.

Never heard.


> Is Docbook really that obscure?

Not really. Actually, I think, it's quite logical.


-- 
Gruß/Regards
  Thomas Schraitle