Open Stack

On Mon, Aug 4, 2014 at 11:48 AM, Andreas Jaeger <aj at suse.com> wrote:

> On 08/04/2014 09:17 AM, Christian Berendt wrote:
> > Andreas proposed to add a linked URL in parentheses after the title/name
> > of the URL instead of directly linking the title/name.
> >
> >
> https://review.openstack.org/#/c/111593/3/doc/arch-design/introduction/section_intended_audience.xml
> >
> > While this makes sense for printed documents like the Architecture
> > Design Guide it does not makes sense for online documents.
> >
> > How should we proceed? At the moment we use both forms in all of our
> > documents.
> >
> > I would really prefer it to have the full URLs in footnotes in printed
> > documents instead of having them in parentheses in the text. This way we
> > have nice online documents and nice printed documents. Is it possible
> > with DocBook to put linked URLs automatically in the footnotes?
>
> I checked the IBM Style Guide and it said that for printed form to add
> the URL in parentheses after the label like I did in that example.
>

Oh, good thinking to look at the IBM Style Guide.


>
> They also have another recommendation: To leave out the http:// in the
> display, so the example would read:
>
> <citetitle>OpenStack Operations Guide</citetitle> (<link
> xlink:href="http://docs.openstack.org/openstack-ops">
> docs.openstack.org/openstack-ops</link>)
>
> Since we're publishing for both print and Online, should we follow
> everywhere the above example - or do this only for those guides that are
> printed?
>

I'd like to have a style that works for both since all of our current
content is single-sourced.

I did mock up some footnote examples in this patch:
https://review.openstack.org/#/c/111823/

But honestly, looking at it, I'm not a huge fan of footnotes, though they
would take care of both print and online.

In the Ops Guide sprint itself, our convention was to use the parens around
the actual clickable link. Then we used O'Reilly's convention, and their
production team had a shortener script. They also have fancy output helpers
that put the full URL in parens, see:
http://chimera.labs.oreilly.com/books/1234000000058/ch02.html#inserting_hyperlinks

Ideal state would be closest to what O'Reilly does for print and online
looking slightly different but being very usable for either output.

Think we can get there? :)
Anne




>
> AFAIK we have these printed guides: Architecture Design, Security Guide,
> HA Guide, Ops Guide.
>
> Andreas
> --
>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
>   SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>    GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)
>     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140804/590628b3/attachment.html>