Proposed Revision of Writer Guide

Earlier (around the end of June) I proposed changes to the Getting
Started guide. That generated some discussion, and someone is working on
a draft revision.

Now I am proposing that we split the Writer Guide into two volumes, as
follows:

1. Essentials

This volume would contain most of what is in Chapters 1 through 12 (but
not bibliographies and possibly not indexes) of the current Writer
Guide, plus Appendix A, some basic field info (for page numbers etc in
headers and footers, and for cross-references), and a new section on
using Writer to write/edit email. Might be some other things people
commonly do that are not covered in the current book, that should be
added.

Probably this would include some reorganisation of topics within
chapters and/or the sequence of chapters in the book.

2. Extras (or Advanced?)

This volume would contain Chapters 13 through 16 of the current book,
plus the bibliographies section of Chapter 12 (and possibly the indexes
section of Ch12), new information on linking or embedding spreadsheets,
audio, and video in Writer documents, info on macros (especially
recording), possibly info on xforms. May be other topics to include,
such as Writer/Web.

Depending on the reactions to this proposal, I will post a draft set of
tables of contents.

I will also soon put all of this on the wiki, if I haven't done so
already. (I keep thinking I put the Getting Starting Toc on the wiki,
but I can't find it.)

--Jean

Hi Jean,

Now I am proposing that we split the Writer Guide into two volumes, as
follows:

I must admit that my initial reaction is that I find it more
convenient to have all the info in one single book, rather than
possible having to consult two guides... 2 cents...

No reason why it can't be packaged as one volume containing two parts, or as
two separate volumes... User's choice how they prefer to get it.

Jean

Hi Jean,

No reason why it can't be packaged as one volume containing two parts, or as
two separate volumes... User's choice how they prefer to get it.

Maybe if it was one volume it would be OK, but I'm not attracted to
the idea of multiplying the number of documentation items we're
supposed to support, except where they cover different/new subjects.
It seems simpler to me as a documentation user and to me as a team
member to have all the info in one work.

Anyway, this is just my own initial reaction. Perhaps after reading
your proposals in greater detail on the wiki, I'd see better what the
advantages would be.

But one other point I'd raise is that maybe it would be more
profitable to fill one of the existing documentation holes rather than
revamping material we already have and that does the job as is?

Again, this is just my 2 cents, since you were looking for feedback.
Let's see what others say...

Hi Jean,

No reason why it can't be packaged as one volume containing two parts, or

as

two separate volumes... User's choice how they prefer to get it.

Maybe if it was one volume it would be OK, but I'm not attracted to
the idea of multiplying the number of documentation items we're
supposed to support, except where they cover different/new subjects.
It seems simpler to me as a documentation user and to me as a team
member to have all the info in one work.

We already provide the docs as individual chapters as well as compiled
books.

Anyway, this is just my own initial reaction. Perhaps after reading
your proposals in greater detail on the wiki, I'd see better what the
advantages would be.

But one other point I'd raise is that maybe it would be more
profitable to fill one of the existing documentation holes rather than
revamping material we already have and that does the job as is?

If we can find people who can and will fill the gaps, I agree that would be
a very good thing to do. In fact, my proposal does include filling some
gaps... which can be done even if reorganization does not occur.

One problem I've seen over the years is the lack of people willing and able
to write new material, especially on more difficult or complex topics. The
Base Guide is a major example. Some volunteers may feel more comfortable
revamping existing material than writing new material, and I would encourage
them to do whatever suits their interest and skill level.

Jean

Regardless of whether the Writer Guide is in 1 or 2 volumes, topics are
missing that need to be written, either as WG chapters or as separate
documents:

* Linking or embedding spreadsheets, audio, and video in Writer
documents
* Using Xforms (we have an outdated tutorial by J David Eisenberg which
we can update and either include or make stand-alone, or both)
* Using Writer/Web (I have a proposed outline which could be used as a
starting point)
* Probably other topics that I've overlooked

In addition, we need to decide whether to include in the WG a chapter on
macros (either the one from Getting Started or a variation).

--Jean

Hi :slight_smile:
For macros, in the short-term, i think use the one that is in the Starter
Guide. It's good to hear about other chapters that need writing from scratch.
I think there are a few people that have been looking for something like that to
do.

Regards from
Tom :slight_smile:

Hi Jean,

Regardless of whether the Writer Guide is in 1 or 2 volumes, topics are
missing that need to be written, either as WG chapters or as separate
documents:

* Linking or embedding spreadsheets, audio, and video in Writer
documents
* Using Xforms (we have an outdated tutorial by J David Eisenberg which
we can update and either include or make stand-alone, or both)
* Using Writer/Web (I have a proposed outline which could be used as a
starting point)
* Probably other topics that I've overlooked

In addition, we need to decide whether to include in the WG a chapter on
macros (either the one from Getting Started or a variation).

Yes, you're right, all those are subjects that need documenting.

As regards macros, maybe in the Writer guide we could focus on
*recording macros* primarily (even though in my Ubuntu's 3.3.2 it's
still counted as an experimental feature) because, as I remember from
recent threads, there was an idea that macros could usefully be
covered in a dedicated guide. Perhaps that could be written into a
guide that would also incorporate the BASIC programming guide awaiting
branding.

More things to add to our growing to-do list...

Hi :slight_smile:
David is it possible for Alfresco to have a single document that appears in more
than one place in such a way that editing it from any of those places updates
everywhere else it exists? Even if it's possible i'm not sure it would be a
great idea but if it's not possible then there is no point discussing that.

Is that what "hard-links" are in linux? ie a lot more than a short-cut?
Regards from
Tom :slight_smile:

Hi Tom,

David is it possible for Alfresco to have a single document that appears in more
than one place in such a way that editing it from any of those places updates
everywhere else it exists?  Even if it's possible i'm not sure it would be a
great idea but if it's not possible then there is no point discussing that.

Yes, it is actually recommended to use links to a single document, if
you need to be able to see it in several locations, rather than having
multiple copies of the same document. So if you edit the document
linked-to then the links will always be pointing to the up-to-date
document.

Is that what "hard-links" are in linux?  ie a lot more than a short-cut?

To understand hard links, you could read this:

http://www.cyberciti.biz/tips/understanding-unixlinux-symbolic-soft-and-hard-links.html

________________________________
From: David Nelson <lists@traduction.biz>
To: documentation@global.libreoffice.org
Sent: Thu, 28 July, 2011 7:40:00
Subject: Re: [libreoffice-documentation] Re: Proposed Revision of Writer Guide

Hi Tom,

On Wed, Jul 27, 2011 at 12:37 PM, Tom Davies <tomdavies04@yahoo.co.uk> wrote:

David is it possible for Alfresco to have a single document that appears in
more
than one place in such a way that editing it from any of those places updates
everywhere else it exists? Even if it's possible i'm not sure it would be a
great idea but if it's not possible then there is no point discussing that.

Yes, it is actually recommended to use links to a single document, if
you need to be able to see it in several locations, rather than having
multiple copies of the same document. So if you edit the document
linked-to then the links will always be pointing to the up-to-date
document.

Is that what "hard-links" are in linux? ie a lot more than a short-cut?

To understand hard links, you could read this:

http://www.cyberciti.biz/tips/understanding-unixlinux-symbolic-soft-and-hard-links.html

David Nelson

Hi :slight_smile:
Ok, so a single chapter about Macros could appear in all the guides and any
editing would update all of them?
Regards from
Tom :slight_smile:

Hi Tom,

Ok, so a single chapter about Macros could appear in all the guides and any
editing would update all of them?

I suppose that, theoretically, yes. But maybe macro coverage for each
app might be somewhat different to be really useful. So maybe not in
practice?

Hi :slight_smile:
Yes, that's where it gets tricky. Could an introduction to the basics of macros
be general enough? That's the question now i guess. If specifics for specific
packages could help people grok macros better while only being a short paragraph
or 2 in the chapter then it might work? Alternatively perhaps just 1 page or 2
added to the chapter in each of the apps?

Regards from
Tom :slight_smile:

Hi,

Hi :slight_smile:
Yes, that's where it gets tricky.  Could an introduction to the basics of macros
be general enough?  That's the question now i guess.  If specifics for specific
packages could help people grok macros better while only being a short paragraph
or 2 in the chapter then it might work?  Alternatively perhaps just 1 page or 2
added to the chapter in each of the apps?

Regards from
Tom :slight_smile:

@Jean: what's your POV about that, Jean?

The current Macros chapter (written by Andrew Pitonyak) in the Getting
Started guide was intended to be fairly generic, though it does focus
mainly on Writer. Andrew then wrote a variation for the Calc Guide,
which focuses more on Calc-related usage. We didn't reuse the macros
chapter from GS in the Writer Guide; at the time we were avoiding
duplication of chapters. However, it would be easy to include the GS
macros chapter in the Writer Guide if people wanted to.

IIRC, we didn't think macros are much used in Impress or Draw, so we
didn't bother with chapters for them. If we did want chapters in those
books, we should ask Andrew for his opinion and see if he has some
suitable material already written to use for examples of use.

I suggest anyone interested in this topic have a look at the existing
two chapters and see what is actually in them and the reuse potential of
that material.

--Jean

________________________________
From: Jean Hollis Weber <jeanweber@gmail.com>
To: documentation@global.libreoffice.org
Sent: Thu, 28 July, 2011 22:00:15
Subject: Re: [libreoffice-documentation] Re: Proposed Revision of Writer Guide

On Thu, 2011-07-28 at 16:03 +0300, David Nelson wrote:

Hi,

On Thu, Jul 28, 2011 at 3:53 PM, Tom Davies <tomdavies04@yahoo.co.uk> wrote:
> Hi :slight_smile:
> Yes, that's where it gets tricky. Could an introduction to the basics of
macros
> be general enough? That's the question now i guess. If specifics for
specific
> packages could help people grok macros better while only being a short
paragraph
> or 2 in the chapter then it might work? Alternatively perhaps just 1 page or
2
> added to the chapter in each of the apps?
>
> Regards from
> Tom :slight_smile:

@Jean: what's your POV about that, Jean?

The current Macros chapter (written by Andrew Pitonyak) in the Getting
Started guide was intended to be fairly generic, though it does focus
mainly on Writer. Andrew then wrote a variation for the Calc Guide,
which focuses more on Calc-related usage. We didn't reuse the macros
chapter from GS in the Writer Guide; at the time we were avoiding
duplication of chapters. However, it would be easy to include the GS
macros chapter in the Writer Guide if people wanted to.

IIRC, we didn't think macros are much used in Impress or Draw, so we
didn't bother with chapters for them. If we did want chapters in those
books, we should ask Andrew for his opinion and see if he has some
suitable material already written to use for examples of use.

I suggest anyone interested in this topic have a look at the existing
two chapters and see what is actually in them and the reuse potential of
that material.

Jean

Hi :slight_smile:
I had forgotten that we had already discussed all that. I had not read the
macro chapters until after reading Jean's post. The one in the GS Guide looks
excellent and very generic. If it is easy to have that in all the guides then i
think it makes the books sold by Lulu more complete.

The Calc Guides' chapter on Macros demands that people read the one in the GS
Guide first. I think it would be better to include the GS chapter in the Calc
Guide being sold at Lulu now that we have a neat way of doing that without
risking fragmentation.

Macros are possibly more heavily used in Calc than in any other of the apps
(apart from Base, possibly) so having 2 chapters there for it makes sense. With
the other 4 apps it would be nice to include the same chapter that is in the GS
"just in case". I don't think they need anything more than that.

Just my first thoughts tho, I'm fairly sure most people have thought about it a
lot more than me.

Regards from
Tom :slight_smile: