Re: [Orgmode] A shorter manual

[Carsten Dominik]

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

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