Re: A shorter manual

[Carsten Dominik <carsten.dominik@gmail.com>]

On Apr 29, 2010, at 7:23 PM, Dan Davison wrote:

> Carsten Dominik <carsten.dominik@gmail.com> writes:
>
>> On Apr 28, 2010, at 8:43 PM, Matti De Craene wrote:
>>
>>>> - 2.8 Drawers
>>>> - 3.2 Column width and alignment
>>>> - 3.3 The Spreadsheet (4 rather technical pages)
>>>> - 7.4 Property Inheritance and 7.5 Column View
>>>> (do beginners really need properties at all ??)
>>>
>>>
>>> I would agree on this list (except maybe drawers).
>>>
>>> If there is room for additional sections maybe:
>>> - include the org ref card as an appendix (which in itself offers a
>>> very good overview of org)
>>> - include some pointers into getting emacs for different OSes and
>>> getting started with emacs. If there would be an O´Reilly book on
>>> Org-mode this would be in the first chapter or so. For people who
>>> started using emacs because of org (like me) the current  
>>> Introduction
>>> might still be too cryptic (?)
>>
>> Hi Dan, Matti,
>>
>> I think I agree, just cannot easliy let go of the spreadsheet
>> as a core feature - you caught me there :-), and you are right, also
>>
>> I would be very glad to hand over the control over this document
>> to either of you or to another volunteer.
>
> Hi Carsten,
>
> I'm afraid I don't want to take responsibility for this (a predictable
> position).

Sure, I understand.

> Apart from anything else there are several areas of Org
> that I don't know enough about. If there isn't a volunteer, perhaps we
> could place this document on Worg, and someone could periodically  
> review
> the changes and judge whether they should be applied to the master  
> copy
> on the Org website? We could request on this list volunteers for  
> someone
> to make specific entries (e.g. adding a "Further reading" section  
> for a
> specific chapter).

Hmmm, I am not sure how efficient this would be.

I have it now down to 40 pages, with live links to the manual and to  
tutorials at the end of each chapter...

http://orgmode.org/orgguide.pdf

I guess I am done here - a volunteer con still take this up...

- Carsten

>
> Dan
>
>
>> Maybe then we could
>> make something really nice out of this experiment - I will not
>> be able to spend much more time on it....
>>
>> - Carsten
>>
>>>
>>>
>>> --
>>>
>>> Matti
>>>
>>>
>>>
>>>
>>> On Wed, Apr 28, 2010 at 7:05 PM, Dan Davison
>>> <davison@stats.ox.ac.uk> wrote:
>>>> Erik Iverson <eriki@ccbr.umn.edu> writes:
>>>>
>>>>> Carsten Dominik wrote:
>>>>>> Dear all,
>>>>>>
>>>>>> with the Org-mode manual moving toward 200 pages,  I am
>>>>>> starting to worry that people with stop in their tracks
>>>>>> when considering Org-mode, just because of the sheer size
>>>>>> of the manual.
>>>>>>
>>>>>> So I did a little experiment.  I took the manual and stripped
>>>>>> everything which could be considered advanced material, but
>>>>>> keeping all features and all basic commands and customizations.
>>>>>>
>>>>>> What remains are about 50 pages.  A document with the same
>>>>>> structure (even the same chapter numbers) as the manual.
>>>>>> I am wondering if it would be useful to have this as a beginners
>>>>>> document - or if the existence of this document would lead
>>>>>> to more confusion than relief.
>>>>>>
>>>>>>    http://orgmode.org/orgguide.pdf
>>>>>>
>>>>>> I don't see this a an alternative for the manual - just
>>>>>> as an additional, rather static document, with little need for
>>>>>> updates.  The manual would continue to be the comprehensive
>>>>>> and constantly updated document.
>>>>>>
>>>>>> Comments are welcome.
>>>>
>>>> Hi Carsten,
>>>>
>>>> I think this would be a good thing to have.
>>>>
>>>> It would be good to have active HTML links to the relevant main
>>>> manual
>>>> sections in PDF and HTML versions. (even if this is not  
>>>> encouraged by
>>>> texinfo format).
>>>>
>>>> I'm tempted to suggest going even a little further than you have
>>>> done.
>>>> If you were to make it shorter, I would suggest removing the
>>>> following
>>>> sections, and to replace removed sections with very short non-
>>>> technical
>>>> advertisements for features that are covered in the main manual.
>>>>
>>>> - 2.8 Drawers
>>>> - 3.2 Column width and alignment
>>>> - 3.3 The Spreadsheet (4 rather technical pages)
>>>> - 7.4 Property Inheritance and 7.5 Column View
>>>> (do beginners really need properties at all ??)
>>>>
>>>> Dan
>>>>
>>>>>
>>>>> I think it's a great idea.  The R project has something called "An
>>>>> Introduction to R" for beginners, separate from the complete  
>>>>> manual.
>>>>> I think that as a beginner, and wondering how to break into
>>>>> learning a
>>>>> new package, that "reading the manual" has certain negative
>>>>> psychological connotations that "reading the intro document" does
>>>>> not,
>>>>> not the least of which is the length of full manual.
>>>>>
>>>>> And since knowing just the basics of org can be immensely
>>>>> beneficial,
>>>>> I think it's even more reason to have a basic intro document.
>>>>>
>>>>> --Erik
>>>>>
>>>>>
>>>>> _______________________________________________
>>>>> Emacs-orgmode mailing list
>>>>> Please use `Reply All' to send replies to the list.
>>>>> Emacs-orgmode@gnu.org
>>>>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>>>>
>>>>
>>>> _______________________________________________
>>>> Emacs-orgmode mailing list
>>>> Please use `Reply All' to send replies to the list.
>>>> Emacs-orgmode@gnu.org
>>>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>>>>
>>
>> - Carsten
>>
>>
>>
>>
>>
>> _______________________________________________
>> Emacs-orgmode mailing list
>> Please use `Reply All' to send replies to the list.
>> Emacs-orgmode@gnu.org
>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode

- Carsten