Documentation template

[jfn]

Hi,

I've uploaded (some of) the documents I've been working with to the drafts in the resource repository. In all, 3 docs:

-- the styles catalog (Calc sheet), created from the SG 3.4

http://alfresco.libreoffice.org/share/page/document-details?nodeRef=workspace://SpacesStore/8fe99883-714e-480f-bfd3-d87e4e9f6f81

-- a map of the paragraphs styles, children of Default (there are some with no parent for which I also have the map I can upload later) in 2 versions: the .mm (freemind) source version and a .png version for those who don't want to install FreeMind.

http://alfresco.libreoffice.org/share/page/document-details?nodeRef=workspace://SpacesStore/ba5f0a98-4763-47ae-8743-4acb89f75313

Here's the structure of the catalog sheet:

-- one sheet per style type, with the following columns

-- CurStyle: the style name, as declared/used in the reference document
-- LinkedWith: the parent style, if any or applicable
-- NextStyle: the next style, if any or applicable.
-- Type: C=Custom; S=Stock
-- Settings: the style settings *if and only if* they differ from the parent
-- UseCase: use cases, from the documentation available (tbd)
-- Questions: some questions that raised while cataloging. Many are pending.
-- NewStyle: a new style alternative, if available now (tbd)

I'll go on entering information in the catalog (ie, use cases, questions). In the meantime we could start discussing. IMO, the first points to be discussed:

-- do we need a naming convention (see also previous Dan's message: "Some suggestions for those beginning work on an updated chapter template")? If yes, which?

-- global styles family: should we adopt an Object-Oriented mind and first set a bunch of "abstract" styles from which the actual styles would be derived? If so, arrange the styles into families/branches. Then define the abstract styles.

-- should we keep in mind a dual template approach: display-only and printed matter templates?

Best regards,

[Tom_Davies]

Hi
Great to see this sort of thing being worked on!  Err we tend to say GS (=Getting Started) but SG makes sense too and is also unique as none of the other guides start with S.  Hmmm, SG is more consistent with the contractions used for other guides.  I'd not thought about it before so lets just say either way is good :) 
Regards from
Tom

[Gary_Schnabl]

A half-decade ago (2005, actually), I was a telecommuting technical editor for Motorola/Freescale Semiconductor prior to Freescale's being spun off with 22,000 of Motorola's then 87,000 employees--based in Austin, primarily. Motorola used conditional text (with Adobe FrameMaker) for standalone user-guide documents for their assemblers, compilers, IDEs, debuggers, etc. Each embedded-microprocessor family (and subfamily) would employ a separate condition, which would be displayed with unique colors as much as possible. With some twenty embedded-microcontroller conditions, their master documents were quite large, considering all the current and legacy CPUs covered on each document.

FrameMaker can easily handle all those conditional texts, though--at least much easier than OOo/LO ever could. Any way, I started drafting some general-purpose conditional-text templates a few weeks ago, whereby various conditions would be covered--print docs, online docs, MS Word migrations (using similar terminology for style names that Word users would typically use), among others. To save my time, I based them upon OOo/LO templates that I had a hand in drafting since 2006. Of course, all that OOo/Libo prefix nonsense for style naming was dispensed with.

I reckon that your dual-template approach would employ LO conditional text? Or did you plan on making separate templates for each conditional usage?

Lastly, I would test how their ODT outputs would convert into EPUB files by calibre (lowercase, as some on LO believe it is Calibre...). Also, I am working on a style guide (US English emphasis, with examples), adapting from various style guides in use at various US universities, etc. When I achieve more critical mass with what I got, they will be posted on my website, and anybody can use them or not, as they wish.

Gary

[jfn]

FrameMaker can easily handle all those conditional texts, though--at
least much easier than OOo/LO ever could.

I've never used FrameMaker, though I hear many positive comments about it on the LibO lists.

Any way, I started drafting
some general-purpose conditional-text templates a few weeks ago, whereby
various conditions would be covered--print docs, online docs, MS Word
migrations (using similar terminology for style names that Word users
would typically use), among others. To save my time, I based them upon
OOo/LO templates that I had a hand in drafting since 2006.

Great!

Of course,
all that OOo/Libo prefix nonsense for style naming was dispensed with.

I reckon that your dual-template approach would employ LO conditional
text? Or did you plan on making separate templates for each conditional
usage?

Yes, this is the primary option. In any case, the target is to minimize the style change when changing target. For the same reason, I always prefer relative font sizes (%) over absolute values (pt).

Lastly, I would test how their ODT outputs would convert into EPUB files
by calibre (lowercase, as some on LO believe it is Calibre...). Also, I
am working on a style guide (US English emphasis, with examples),
adapting from various style guides in use at various US universities,
etc. When I achieve more critical mass with what I got, they will be
posted on my website, and anybody can use them or not, as they wish.

Thanks for sharing.