You are viewing a plain text version of this content. The canonical link for it is here.
Posted to doc@openoffice.apache.org by Rob Weir <ro...@apache.org> on 2013/01/07 18:58:46 UTC
Proposal for Moving Forward with Documentation
We have a small set of volunteers right now, but it should be easy to
attract more if we do a "Call for Volunteers". This worked very well
for translators, marketing and QA, for example. But what we learned
there is that you really need to have a project structure in place
before bringing in new volunteers. Otherwise everyone just sits
around, waiting for something to happen.
So this suggests the following steps:
1) Establish a basic list of deliverables for the AOO 4.0 time frame.
Realistically, what should we aim for in the April/May time frame?
Maybe think of this as a minimal goal, plus some "stretch goals" that
we might be able to do if we have more volunteers.
2) Do some basic preparatory work for at least some of the deliverables, say:
a) design the document templates
b) define a table of contents or rough content outline for each core deliverable
c) agree on what the workflow will look like: authoring, editing,
public review, translation, publication, etc. We don't need 100%
detail, but we need enough to have a meaningful agreement among
ourselves what the process should look like.
3) Call for Volunteers -- By this point we've defined enough of a
framework that we can bring in new volunteers without it being too
chaotic.
4) Execute
5) Deliver
Does this make sense?
-Rob
Re: Proposal for Moving Forward with Documentation
Posted by Andrew Douglas Pitonyak <an...@pitonyak.org>.
What is the document title? General Concepts? Getting Started?
Introduction to AOO?
> 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.
Re: Proposal for Moving Forward with Documentation
Posted by Andrew Douglas Pitonyak <an...@pitonyak.org>.
On 01/09/2013 01:24 AM, Guy Waterval wrote:
> Hi all,
>
>
> 2013/1/8 Andrea Pescetti <pe...@apache.org>
>
>> Rob Weir wrote:
>>
>> On Tue, Jan 8, 2013 at 7:12 AM, RGB ES wrote:
>>>> http://www.microsoft.com/**About/Legal/EN/US/**IntellectualProperty/**
>>>> Permissions/Default.aspx#ERG<http://www.microsoft.com/About/Legal/EN/US/IntellectualProperty/Permissions/Default.aspx#ERG>
>>>> "4. Do not use screen shots that contain third-party content."
>>>> This and number 2 "Do not use portions of screen shots" are problematic.
>>>> I
>>>> don't think they will ever make problems for this, but...
>>>>
>>> I think this means, don't use portions of a screenshot where the
>>> screenshot is of a Microsoft copyrighted image. So don't use portion
>>> of Excel or Word screenshot. But we can use a portion of our own UI.
>>>
>> This was discussed extensively some years ago, concluding that the
>> OpenOffice documentation could not use screenshots that included the
>> Windows widgets and window decorations (like the X button to close the
>> window).
>>
>> I know that everybody can just go to the nearest public library and find
>> dozen of end-user software manuals contradicting this, so I don't know how
>> seriously this issue should be taken. Fact is, ODFAuthors (used to?) take
>> all their screenshots on free operating systems due to this.
>>
> The reverse case is for me more interesting. Books about OpenOffice, but
> not under a free license, sometimes written by free authors, with a
> disclaimer saying that you are not allowed to reproduce or modify any
> slight part of the book. OK, the disclaimer comes from the publisher, but
> what about the UI screenshots, dialog boxes, ...? Nobody reacts, so I think
> there is no risk, especially with MS which is not a stupid company.
>
> A+
Although I expect that it is not a problem, some of the wording seems a
bit strange; for example, disallowing "portions of screen shots", which
sounds like you must always show the entire screen.
--
Andrew Pitonyak
My Macro Document: http://www.pitonyak.org/AndrewMacro.odt
Info: http://www.pitonyak.org/oo.php
Re: Proposal for Moving Forward with Documentation
Posted by Guy Waterval <wa...@gmail.com>.
Hi all,
2013/1/8 Andrea Pescetti <pe...@apache.org>
> Rob Weir wrote:
>
> On Tue, Jan 8, 2013 at 7:12 AM, RGB ES wrote:
>>
>>> http://www.microsoft.com/**About/Legal/EN/US/**IntellectualProperty/**
>>> Permissions/Default.aspx#ERG<http://www.microsoft.com/About/Legal/EN/US/IntellectualProperty/Permissions/Default.aspx#ERG>
>>> "4. Do not use screen shots that contain third-party content."
>>> This and number 2 "Do not use portions of screen shots" are problematic.
>>> I
>>> don't think they will ever make problems for this, but...
>>>
>> I think this means, don't use portions of a screenshot where the
>> screenshot is of a Microsoft copyrighted image. So don't use portion
>> of Excel or Word screenshot. But we can use a portion of our own UI.
>>
>
> This was discussed extensively some years ago, concluding that the
> OpenOffice documentation could not use screenshots that included the
> Windows widgets and window decorations (like the X button to close the
> window).
>
> I know that everybody can just go to the nearest public library and find
> dozen of end-user software manuals contradicting this, so I don't know how
> seriously this issue should be taken. Fact is, ODFAuthors (used to?) take
> all their screenshots on free operating systems due to this.
>
The reverse case is for me more interesting. Books about OpenOffice, but
not under a free license, sometimes written by free authors, with a
disclaimer saying that you are not allowed to reproduce or modify any
slight part of the book. OK, the disclaimer comes from the publisher, but
what about the UI screenshots, dialog boxes, ...? Nobody reacts, so I think
there is no risk, especially with MS which is not a stupid company.
A+
--
gw
Re: Proposal for Moving Forward with Documentation
Posted by Rob Weir <ro...@apache.org>.
On Tue, Jan 8, 2013 at 5:07 PM, Andrea Pescetti <pe...@apache.org> wrote:
> Rob Weir wrote:
>
>> On Tue, Jan 8, 2013 at 7:12 AM, RGB ES wrote:
>>>
>>>
>>> http://www.microsoft.com/About/Legal/EN/US/IntellectualProperty/Permissions/Default.aspx#ERG
>>> "4. Do not use screen shots that contain third-party content."
>>> This and number 2 "Do not use portions of screen shots" are problematic.
>>> I
>>> don't think they will ever make problems for this, but...
>>
>> I think this means, don't use portions of a screenshot where the
>> screenshot is of a Microsoft copyrighted image. So don't use portion
>> of Excel or Word screenshot. But we can use a portion of our own UI.
>
>
> This was discussed extensively some years ago, concluding that the
> OpenOffice documentation could not use screenshots that included the Windows
> widgets and window decorations (like the X button to close the window).
>
> I know that everybody can just go to the nearest public library and find
> dozen of end-user software manuals contradicting this, so I don't know how
> seriously this issue should be taken. Fact is, ODFAuthors (used to?) take
> all their screenshots on free operating systems due to this.
>
It depends on how paranoid you want to be, For example, wouldn't
taking the Linux screenshots trigger a GPL dependency? Would that be
incompatible with doing the documentation under ALv2? I think you get
into trouble like this unless we have a proper sense of what is "fair
use".
-Rob
> Regards,
> Andrea.
Re: Proposal for Moving Forward with Documentation
Posted by Andrea Pescetti <pe...@apache.org>.
Rob Weir wrote:
> On Tue, Jan 8, 2013 at 7:12 AM, RGB ES wrote:
>> http://www.microsoft.com/About/Legal/EN/US/IntellectualProperty/Permissions/Default.aspx#ERG
>> "4. Do not use screen shots that contain third-party content."
>> This and number 2 "Do not use portions of screen shots" are problematic. I
>> don't think they will ever make problems for this, but...
> I think this means, don't use portions of a screenshot where the
> screenshot is of a Microsoft copyrighted image. So don't use portion
> of Excel or Word screenshot. But we can use a portion of our own UI.
This was discussed extensively some years ago, concluding that the
OpenOffice documentation could not use screenshots that included the
Windows widgets and window decorations (like the X button to close the
window).
I know that everybody can just go to the nearest public library and find
dozen of end-user software manuals contradicting this, so I don't know
how seriously this issue should be taken. Fact is, ODFAuthors (used to?)
take all their screenshots on free operating systems due to this.
Regards,
Andrea.
Re: Proposal for Moving Forward with Documentation
Posted by Rob Weir <ro...@apache.org>.
On Tue, Jan 8, 2013 at 7:12 AM, RGB ES <rg...@gmail.com> wrote:
> 2013/1/7 Rob Weir <ro...@apache.org>
>
>> We have a small set of volunteers right now, but it should be easy to
>> attract more if we do a "Call for Volunteers". This worked very well
>> for translators, marketing and QA, for example. But what we learned
>> there is that you really need to have a project structure in place
>> before bringing in new volunteers. Otherwise everyone just sits
>> around, waiting for something to happen.
>>
>
> +1
>
>
>
>>
>> So this suggests the following steps:
>>
>> 1) Establish a basic list of deliverables for the AOO 4.0 time frame.
>> Realistically, what should we aim for in the April/May time frame?
>> Maybe think of this as a minimal goal, plus some "stretch goals" that
>> we might be able to do if we have more volunteers.
>>
>
> I think we should aim for an online documentation on the wiki, with the
> "basics" and maybe some "cheat sheets" for each component. Content is more
> important than format and the wiki is the easiest way to involve more
> people and get content ready in a short time.
>
I'm fine with using the wiki as an authoring environment. It even
has some advantages as final format:
1) It is a webpage, so it is indexed by Google and easily findable
2) As a wiki it encourages user contributions and improvements
3) It allows us to make the documentation be a "living document".
The downside is there is more work to get the content into an PDF,
ebook or printer book format. But not impossible. We just need to
find or develop the right tool chain. But since we're using the MWiki
we'll probably find out that someone has already solved this problem
for us.
>
>
>>
>>
>> 2) Do some basic preparatory work for at least some of the deliverables,
>> say:
>>
>> a) design the document templates
>>
>
> If we point to the wiki, templates for "real books" can be done later, but
> there are other things we needs to agree on: for example, screenshots. If
> every author take screenshots on their system we will end with a
> very heterogeneous collection of OSs and desktop themes, giving a
> very unprofessional look. In fact, if I read it right, using screen shots
> taken on windows could not be completely "legal":
>
Right. Even if we use the wiki there are still some conventions we'll
want to adopt, even if they are not in the form of "templates". What
do we need to agree on to ensure a common look & feel? Also,
agreement on editorial conventions, e.g., do we refer to the user
directly in the second person, or only as third person?
Also, do we want to make individual, standalone guides on the wiki?
Or do we want to hyperlink them into a larger whole, an "Encyclopedia
OpenOffice"? We have the ability, if we chose, to avoid the kind of
tradeoffs that accompany traditional documentation, where you are
either good for beginners, or are detailed. Task-oriented or
reference? We can be both at the same time, with hypertext and the
right structure.
>
> http://www.microsoft.com/About/Legal/EN/US/IntellectualProperty/Permissions/Default.aspx#ERG
>
> "4. Do not use screen shots that contain third-party content."
>
> This and number 2 "Do not use portions of screen shots" are problematic. I
> don't think they will ever make problems for this, but...
>
I think this means, don't use portions of a screenshot where the
screenshot is of a Microsoft copyrighted image. So don't use portion
of Excel or Word screenshot. But we can use a portion of our own UI.
>
>
>>
>> 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.
>
I'll take a look. Thanks for putting that together.
-Rob
>
>
>>
>> c) agree on what the workflow will look like: authoring, editing,
>> public review, translation, publication, etc. We don't need 100%
>> detail, but we need enough to have a meaningful agreement among
>> ourselves what the process should look like.
>>
>>
>> 3) Call for Volunteers -- By this point we've defined enough of a
>> framework that we can bring in new volunteers without it being too
>> chaotic.
>>
>>
>> 4) Execute
>>
>>
>> 5) Deliver
>>
>>
>> Does this make sense?
>>
>
> Perfect sense! Thanks for starting this discussion.
>
> Regards
> Ricardo
>
>
>
>>
>> -Rob
>>
Re: Proposal for Moving Forward with Documentation
Posted by RGB ES <rg...@gmail.com>.
2013/1/9 Rob Weir <ro...@apache.org>
> On Tue, Jan 8, 2013 at 7:12 AM, RGB ES <rg...@gmail.com> wrote:
> .
> .
> .
> >
> > 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.
> >
> >
>
> So how would we map that to wiki pages? I assume having one giant
> page is bad.
>
Indeed!
>
> One wiki page per chapter? One wiki page per section?
>
> How granular do we want to get with how this is mapped onto wiki pages?
>
On Mwiki you can build a "tree" of pages. For example,
Writer (with the index for that chapter)
Writer/Introduction
Writer/Introduction/Editing_simple_text
...
Writer/Styles
Writer/Styles/Paragraph
...
>
> Are there any good examples to look at, for documentation done by
> MWiki? Something we can look at for a model?
>
You can see something quite similar to the proposed TOC on the ES wiki
http://wiki.openoffice.org/wiki/ES/Manuales/GuiaAOO
I cannot warranty that it's good, but at least it's an example ;)
Regards
Ricardo
>
> -Rob
>
Re: Proposal for Moving Forward with Documentation
Posted by Rob Weir <ro...@apache.org>.
On Tue, Jan 8, 2013 at 7:12 AM, RGB ES <rg...@gmail.com> wrote:
.
.
.
>
> 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.
>
>
So how would we map that to wiki pages? I assume having one giant
page is bad.
One wiki page per chapter? One wiki page per section?
How granular do we want to get with how this is mapped onto wiki pages?
Are there any good examples to look at, for documentation done by
MWiki? Something we can look at for a model?
-Rob
Re: Proposal for Moving Forward with Documentation
Posted by 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: Proposal for Moving Forward with Documentation
Posted by 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.
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?.
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.
Many thanks
--
gw
>
>
>
Re: Proposal for Moving Forward with Documentation
Posted by RGB ES <rg...@gmail.com>.
2013/1/7 Rob Weir <ro...@apache.org>
> We have a small set of volunteers right now, but it should be easy to
> attract more if we do a "Call for Volunteers". This worked very well
> for translators, marketing and QA, for example. But what we learned
> there is that you really need to have a project structure in place
> before bringing in new volunteers. Otherwise everyone just sits
> around, waiting for something to happen.
>
+1
>
> So this suggests the following steps:
>
> 1) Establish a basic list of deliverables for the AOO 4.0 time frame.
> Realistically, what should we aim for in the April/May time frame?
> Maybe think of this as a minimal goal, plus some "stretch goals" that
> we might be able to do if we have more volunteers.
>
I think we should aim for an online documentation on the wiki, with the
"basics" and maybe some "cheat sheets" for each component. Content is more
important than format and the wiki is the easiest way to involve more
people and get content ready in a short time.
>
>
> 2) Do some basic preparatory work for at least some of the deliverables,
> say:
>
> a) design the document templates
>
If we point to the wiki, templates for "real books" can be done later, but
there are other things we needs to agree on: for example, screenshots. If
every author take screenshots on their system we will end with a
very heterogeneous collection of OSs and desktop themes, giving a
very unprofessional look. In fact, if I read it right, using screen shots
taken on windows could not be completely "legal":
http://www.microsoft.com/About/Legal/EN/US/IntellectualProperty/Permissions/Default.aspx#ERG
"4. Do not use screen shots that contain third-party content."
This and number 2 "Do not use portions of screen shots" are problematic. I
don't think they will ever make problems for this, but...
>
> 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.
>
> c) agree on what the workflow will look like: authoring, editing,
> public review, translation, publication, etc. We don't need 100%
> detail, but we need enough to have a meaningful agreement among
> ourselves what the process should look like.
>
>
> 3) Call for Volunteers -- By this point we've defined enough of a
> framework that we can bring in new volunteers without it being too
> chaotic.
>
>
> 4) Execute
>
>
> 5) Deliver
>
>
> Does this make sense?
>
Perfect sense! Thanks for starting this discussion.
Regards
Ricardo
>
> -Rob
>