openoffice-doc mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Keith N. McKenna" <meriodoc_brandyb...@yahoo.com>
Subject Re: Possible workflow [was: Re: Proposal for Moving Forward with Documentation]
Date Mon, 14 Jan 2013 19:13:52 GMT
Rob;

There is already a Notes template that could be used for relaying that a 
feature is new and with with what revision. If you look at section 7.2 
of the Wiki Editing Policy at 
http://wiki.openoffice.org/wiki/Documentation/Dashboard/Wiki_Editing_Policy#List_of_Existing_Documentation_Templates

there is a list of existing documentation templates and a brief 
description of thereuse. Many are obsolete, but most are still useable. 
There is also a new one that I have to add to that section that I 
created for the the FAQ merge clean-up. It is {{AOO}} and it expands  to 
Apache OpenOffice.

Regards
Keith

Rob Weir wrote:
> On Sun, Jan 13, 2013 at 5:57 PM, Regina Henschel
> <rb.henschel@t-online.de> wrote:
>> Hi Ricardo,
>>
>> RGB ES schrieb:
>>
>>> To start writing the user guide on the Wiki, I propose the following page
>>> structure
>>>
>>> /wiki/Documentation/UserGuide
>>> /wiki/Documentation/UserGuide/Guidelines    ← guidelines for Writers
>>> /wiki/Documentation/UserGuide/4_0     ← Index for the user guide for AOO
>>> 4.0, following the proposed TOC.(1) (In a future, we can start with 4_1,
>>> etc.)
>>>
>>> Then, each part of the document on different sub-pages
>>>
>>> /wiki/Documentation/UserGuide/4_0/General     ← sub-index for "General
>>> concepts..." chapter
>>> /wiki/Documentation/UserGuide/4_0/General/UI
>>> /wiki/Documentation/UserGuide/4_0/General/Formatting
>>> /wiki/Documentation/UserGuide/4_0/General/Autocorrect
>>> ...
>>> /wiki/Documentation/UserGuide/4_0/Tips     ← sub-index for the "Cheat
>>> sheets" chapter
>>> /wiki/Documentation/UserGuide/4_0/Tips/Writer
>>> /wiki/Documentation/UserGuide/4_0/Tips/Calc
>>> ...
>>> /wiki/Documentation/UserGuide/4_0/Writer     ← sub-index for Writer's
>>> guide
>>> /wiki/Documentation/UserGuide/4_0/Writer/Intro
>>> ...
>>> and so on.
>>
>> I propose to omit the version number level. As can be seen for ODFAuthors it
>> is unlikely, that all documents are new written for a new version and
>> sometimes it is not needed at all. LibreOffice 4.0 is in RC1, but some
>> documents are for 3.4, some for 3.5, and 3.6 is missing totally. The
>> situation becomes worse, if you think of documentations in other languages.
>>
> This is a good point.   I wonder if there is an easy way to have a
> single documentation set, at least for the roughly-compatible 4.x
> series of releases?  And then within that single documentation set
> have a convention for indicating a particular feature exists, say,
> only in version 4.2.1?  If 90%+ of the content would be the same in
> the 4.x series, then this could be an efficient way of doing it.
>
> -Rob
>
>
>
>> I propose this way: Use a hierarchy
>> /wiki/Documentation/UserGuide/Tips/Writer
>> or
>> /wiki/Documentation/UserGuide/Writer/Tips
>> I'm not sure about the best order.
>>
>> If some content becomes outdated and has to be replaced, then generate a new
>> page with the same title, but a version addition.
>>
>> Example: A outdated content in the path
>> /wiki/Documentation/UserGuide/General/UI/Customize_Toolbar
>> would be copied to a path
>> /wiki/Documentation/UserGuide/General/UI/Customize_Toolbar_3_4
>> and the original page gets a comment line with a link to the old version and
>> the old version gets a comment line back to the newer version.
>> This has to be done by the person, who writes the new content.
>>
>> This has the advantage, that there will be no tree of empty pages, but the
>> user will always come to the most actual document, when he starts in
>> /wiki/Documentation and follows the tree.
>>
>> In the start, when not enough actual content is available, this single
>> comment line can link to the existing ODFAuthors 3.3 or 3.2 documents or
>> other suitable wiki pages.
>>
>>
>>
>>> The idea is to create all the pages at once, with just the categories
>>> "Documentation" and "UserGuide" and a template similar to the one we use
>>> on
>>> the ES wiki(2) for "work in process new pages", that we can call "Draft"
>>> (not sure if there is one already: I cannot find it).
>>
>> Creating a new "UserGuide" section is OK, but same other sections need to be
>> there from the beginning too. I think of pathes to the developers guide, to
>> the building guide, to the QA tutorials, to the Calc functions reference.
>>
>>
>>> In parallel, we can start discussing about writing style, screenshots
>>> (desktop theme...) and related problems on other topics.
>>
>> There is the page
>> http://wiki.openoffice.org/wiki/Documentation/Dashboard/Wiki_Editing_Policy.
>> It is already fairly good, and can be used as start. Adaption to AOO is of
>> cause needed.
>>
>>
>>> After "seeding" some pages with content we start a call for authors and
>>> the
>>> "real writing"(3). Finally, when the author is ready he/she calls for
>>> review/proof reading and when every is OK we delete the "Draft" template.
>>>
>>> What do you think?
>>
>> I fear, a lot a pages will stay "draft" for ever.
>>
>> What are your plans about the old Dokumentation hierarchy ?
>> http://wiki.openoffice.org/wiki/Documentation/Dashboard/Wiki_Editing_Policy#Structure_of_the_Documentation_Section_of_the_Wiki
>>
>> Kind regards
>> Regina
>>


Mime
View raw message