Re: [Orgmode] A shorter manual

[Dan Davison]

Carsten Dominik <address@hidden> writes:

> On Apr 29, 2010, at 7:23 PM, Dan Davison wrote:
>
>> Carsten Dominik <address@hidden> 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

That looks great. Having the links to Worg and other tutorials is really
nice.

I noticed a couple of typos in the live links:

- p.29  in John Wiegely's name
- p.36 "persentation"

and to split hairs
- p.33 "from the manual" -> "of the manual" for consistency

Dan




>
> 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
>>>> <address@hidden> wrote:
>>>>> Erik Iverson <address@hidden> 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.
>>>>>> address@hidden
>>>>>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>>>>>
>>>>>
>>>>> _______________________________________________
>>>>> Emacs-orgmode mailing list
>>>>> Please use `Reply All' to send replies to the list.
>>>>> address@hidden
>>>>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>>>>>
>>>
>>> - Carsten
>>>
>>>
>>>
>>>
>>>
>>> _______________________________________________
>>> Emacs-orgmode mailing list
>>> Please use `Reply All' to send replies to the list.
>>> address@hidden
>>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>
> - Carsten
>
>
>
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Please use `Reply All' to send replies to the list.
> address@hidden
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode