You are viewing a plain text version of this content. The canonical link for it is here.
Posted to doc@openoffice.apache.org by RGB ES <rg...@gmail.com> on 2013/01/13 22:23:02 UTC
Possible workflow [was: Re: Proposal for Moving Forward with Documentation]
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.
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).
In parallel, we can start discussing about writing style, screenshots
(desktop theme...) and related problems on other topics.
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?
(1)
https://cwiki.apache.org/confluence/display/OOOUSERS/Details+on+Scenario+3#DetailsonScenario3-ProposedTOC
(2) http://wiki.openoffice.org/wiki/Template:ES/AyudaWiki/Borrador
(3) Related question: any time frame for when dev builds with new UI
elements will be available?
Regards
Ricardo
2013/1/10 RGB ES <rg...@gmail.com>
> Hi,
>
> 2013/1/10 Guy Waterval <wa...@gmail.com>
>
>> Hi all,
>> Hi Ricardo,
>>
>> 2013/1/8 RGB ES <rg...@gmail.com>
>>
>> > 2013/1/7 Rob Weir <ro...@apache.org>
>> >
>> >
>> > Snip
>>
>>
>> > > b) define a table of contents or rough content outline for each core
>> > > deliverable
>> > >
>> >
>> > We can start from this draft
>> >
>> >
>> >
>> https://cwiki.apache.org/confluence/display/OOOUSERS/Details+on+Scenario+3#DetailsonScenario3-ProposedTOC
>> >
>> > maybe focusing on the first two chapters for now.
>> >
>>
>> Looking at the TOC, I really think that it's a good approach to get a
>> reduced volume of documentation and make it easier to update. Such
>> organisation could also perhaps reduce the learning curve of the program.
>>
>
> Let's hope that: AOO is really easy to use, but only when you know how to
> use it :)
>
>
>
>> I wonder if we could also introduce or not the following in the chapter
>> "General concepts"
>>
>>
>> - links which are present in the different modules.
>> - tables : a general introduction and global manipulations (specific
>> issues for Writer being developped in the Writer module).
>> - Fields : introduction in each module or a general introduction in
>> the
>> general concepts chapter?.
>>
>
>
> My idea was to left the "general concepts" chapter as general as possible,
> to use it as reference on the other chapters. On the Writer chapter there
> is an area devoted to tables and fields. For a quick comment on those
> subjects, the "cheat sheets" chapter could be better, IMO.
>
>
>
>>
>> Another issue about terminology.
>> Is it possible to consider tables, fields and links as inserable objetcts
>> or not. Of course in Writer they belong to the text layer, but in Draw and
>> Impress, they have an object behaviour as images. These elements are for
>> me
>> always difficult to classify. Which category do you recommand? For fields
>> and links I usually use "special text zones" but I'm not sure if this is
>> the correct approach.
>>
>
> Agree, and indeed that's another reason to talk about tables on each
> component and not on the general chapter. Tables on Draw and Impress are
> rather limited compared with tables on Writer.
>
> Talking about terminology, field can be considered as "automated text".
> Some fields (chapter and page field, for example) can be considered as
> "contextual text" also: their value depends on the point they are inserted.
> Links are difficult to categorize: we have links as in html links but also
> links as cross references, as footnote anchors... maybe it's better to
> not categorize them at all :)
>
> Regards
> Ricardo
>
>
>
>>
>> Many thanks
>> --
>> gw
>>
>> >
>> >
>> >
>>
>
>
Re: Possible workflow [was: Re: Proposal for Moving Forward with Documentation]
Posted by Rob Weir <ro...@apache.org>.
On Mon, Jan 14, 2013 at 2:13 PM, Keith N. McKenna
<me...@yahoo.com> wrote:
> 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 there use. 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.
>
OK. This is good to know. Thanks!
-Rob
> Regards
> Keith
>
> Rob Weir wrote:
>
> On Sun, Jan 13, 2013 at 5:57 PM, Regina Henschel
> <rb...@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
>
>
Re: Possible workflow [was: Re: Proposal for Moving Forward with
Documentation]
Posted by "Keith N. McKenna" <me...@yahoo.com>.
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...@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
>>
Re: Possible workflow [was: Re: Proposal for Moving Forward with Documentation]
Posted by Rob Weir <ro...@apache.org>.
On Sun, Jan 13, 2013 at 5:57 PM, Regina Henschel
<rb...@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
>
Re: Possible workflow [was: Re: Proposal for Moving Forward with Documentation]
Posted by RGB ES <rg...@gmail.com>.
2013/1/13 Regina Henschel <rb...@t-online.de>
> Hi Ricardo,
>
> RGB ES schrieb:
>
> <snip>
>
>
> 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.
>
> 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.
>
Good point! I like the idea of moving outdated content to sub-pages.
>
> 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.
Sure. We can update the main documentation page(1) to gather all those
elements on one place.
(1) http://wiki.openoffice.org/wiki/Documentation
>
>
>
>> 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<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.
Thanks for the link! Looking there I see that the DraftPage template is
already present: {{Documentation/DraftPage}}
>
>
>
>> 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<http://wiki.openoffice.org/wiki/Documentation/Dashboard/Wiki_Editing_Policy#Structure_of_the_Documentation_Section_of_the_Wiki>
No plans, for the moment. I just tried to start the discussion for a self
contained 4.0 user guide written from scratch and easy to maintain.
The structure of the Documentation section on the wiki is indeed quite
complex and it is difficult for a new user to tell apart what's still
valid. Maybe we need to make a completely fresh start here, moving old
content to a "legacy" section... but on the other hand we cannot left the
site empty.
Regards
Ricardo
>
>
> Kind regards
> Regina
>
>
Re: Possible workflow [was: Re: Proposal for Moving Forward with
Documentation]
Posted by Regina Henschel <rb...@t-online.de>.
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.
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
Re: Possible workflow [was: Re: Proposal for Moving Forward with
Documentation]
Posted by Andrea Pescetti <pe...@apache.org>.
RGB ES wrote:
> (3) Related question: any time frame for when dev builds with new UI
> elements will be available?
You should CC https://issues.apache.org/ooo/show_bug.cgi?id=121420 ; I
see that Andre has checked in code regularly, but still only on the
sidebar branch (which means you should compile it yourself, or wait for
the integration, that will be reported in the issue page).
I believe that Andre will make a sidebar branch build available as soon
as the feature is complete, even before merging to trunk. Our current
snapshot builds are from trunk, i.e., the main code line, and have no
trace of Andre's work so far.
Regards,
Andrea.