documentation feature: typical .org files as starting points along with screencasts

documentation feature: typical .org files as starting points along with screencasts

[hj-orgmode-1]

  Hello,

  First of all, orgmode rocks!

   I am trying to work with with orgmode  for a few months now, and I 
feel like I am still only scratching the surface. I've read the manual, 
and the online docs, yet fully functional access to some features eludes 
me still.

   I would find it tremendously useful if, perhaps as a part of the 
documentation, there were several sample .org files, at various levels 
of complexity (features used) _along_ _with_ a quick and simple screen 
cast of its features being used in a real-life scenario. ( I find it 
most useful for such screen casts to display key presses as they occur 
... is there a "plugin" which would 1) show the keys being pressed and 
2) also show the resulting functions being invoked by those keystrokes? 
). Repeatedly I've spent more than an hour trying to figure out what 
happened when I haven't noticed that by mistake that I've pressed some 
weird key combo which has placed my orgmode/emacs session in an 
incomprehensible state - e.g. narrowing a buffer. Had I known which keys 
I had pressed by mistake, or at least the functions that they involved, 
I could have looked up the manual to see how to "undo" such mess. But 
when you don't know that your state is being called "narrowing buffer", 
you have no clue what just happened and that you should find out how to 
"widen" it again. ( That is very, VERY frustrating for an emacs/orgmode 
newbie. Someone please advise how to turn on a log of keystrokes and 
functions being invoked by those keystrokes. ... Consider having this on 
as default for newbies. )

  It seems to me that to get people started without unnecessary 
frustrations, we might want to put into the docs something like:

To include feature : timestamp-based unique IDs : Configure emacs thusly 
: <insert a patch here perhaps with a video/screencast showing manual 
insertion> and then see how this works <a video here>; ...  same for 
features like  HTML export, literal programming, custom timestamp 
(perhaps with down-to-seconds resolution) custom, etc

  I believe if I saw in a few screen casts how the orgmode 
"professionals" use orgmode, and had access to their sample orgmode 
files which I could follow along and literally identically modify during 
the screencast, I would be much father (and perhaps even happier) with 
the use of orgmode. I think the most crucial point for newbies is being 
able to literally follow the screencast along, perfectly replicating the 
screen cast results in their emacs / evil / spacemacs setup.

If people would want to send me URLs for their sample .org files for 
which they also have a demo screen cast on how to use their features, I 
would like to pull these together and create a section for the docs with 
these.

  Guys! You are a wonderful bunch and you are perfecting an amazing 
software! ... Let the world get more of a taste of your amazing work.

   Thanks so much for orgmode!

     John

Re: documentation feature: typical .org files as starting points along with screencasts

[Ihor Radchenko]

>   Hello,

Welcome to org community ;)

>    I would find it tremendously useful if, perhaps as a part of the 
> documentation, there were several sample .org files, at various levels 
> of complexity (features used) _along_ _with_ a quick and simple screen 
> cast of its features being used in a real-life scenario. ( I find it 
> most useful for such screen casts to display key presses as they occur 
> ... is there a "plugin" which would 1) show the keys being pressed and 
> 2) also show the resulting functions being invoked by those keystrokes? 
> ).

You may find the tutorial section org org-mode wiki useful:
https://orgmode.org/worg/org-tutorials/index.html
Not all, but some of the video tutorials there also contain a github
repo with reference configuration or org files.

>   It seems to me that to get people started without unnecessary 
> frustrations, we might want to put into the docs something like:
>
> To include feature : timestamp-based unique IDs : Configure emacs thusly 
> : <insert a patch here perhaps with a video/screencast showing manual 
> insertion> and then see how this works <a video here>; ...  same for 
> features like  HTML export, literal programming, custom timestamp 
> (perhaps with down-to-seconds resolution) custom, etc

It may be more practical to link the relevant wiki sections from the
org manual itself. Then, we can formalise wiki article formats to
include videos, configuration, and org examples.

> Repeatedly I've spent more than an hour trying to figure out what 
> happened when I haven't noticed that by mistake that I've pressed some 
> weird key combo which has placed my orgmode/emacs session in an 
> incomprehensible state - e.g. narrowing a buffer.

Fair point. Narrowing functionality is disabled in Emacs by default and
shows a warning when a user tries to execute narrowing commands.
However, this is not the case for narrow-related org-mode functions. We
should probably disable the narrow commands via

(put 'function 'disabled t)

Then, news users will at least be warned that command may create a
confusion.

> Had I known which keys 
> I had pressed by mistake, or at least the functions that they involved, 
> I could have looked up the manual to see how to "undo" such mess. But 
> when you don't know that your state is being called "narrowing buffer", 
> you have no clue what just happened and that you should find out how to 
> "widen" it again. ( That is very, VERY frustrating for an emacs/orgmode 
> newbie. Someone please advise how to turn on a log of keystrokes and 
> functions being invoked by those keystrokes. ... Consider having this on 
> as default for newbies. )

For future, you can always execute M-x view-lossage to see the
keystrokes you pressed earlier and the functions called by those
keystrokes. This command is a part of Emacs itself.

>   I believe if I saw in a few screen casts how the orgmode 
> "professionals" use orgmode, and had access to their sample orgmode 
> files which I could follow along and literally identically modify during 
> the screencast, I would be much father (and perhaps even happier) with 
> the use of orgmode. I think the most crucial point for newbies is being 
> able to literally follow the screencast along, perfectly replicating the 
> screen cast results in their emacs / evil / spacemacs setup.

> If people would want to send me URLs for their sample .org files for 
> which they also have a demo screen cast on how to use their features, I 
> would like to pull these together and create a section for the docs with 
> these.

Creating a screencast or even example .org file is not trivial - we
cannot just share own personal .org files in public in majority of
cases. A good screencast should also not rely on the other parts of
personal configuration. The problem is that personal config tends to get
very, *very* large for long-time users (and we are so used to it that it
is easy to forget that something is actually not default setting). A
simple example: I am using personalised (different from vim) modal
editing with non-standard key bindings - recorded keystrokes would not
help a new user at all.

Also, it is not clear what features are worth sharing.

If you are willing to invest your time in creating the docs/worg pages,
you may probably create a list of features you think are good to be
documented and then request volunteers to create screencasts (maybe also
contact the existing video creators making Emacs videos) along with
example org files (using their personal config). Then, it will be
necessary to make sure that the screencasts can actually be reproduced
from default org-mode settings.

If you are willing to do it (and if you will be granted edit rights to
worg), I can probably help you with initial screencasts during my spare
time. 

Best,
Ihor


hj-orgmode-1@hj.proberto.com writes:

>   Hello,
>
>   First of all, orgmode rocks!
>
>    I am trying to work with with orgmode  for a few months now, and I 
> feel like I am still only scratching the surface. I've read the manual, 
> and the online docs, yet fully functional access to some features eludes 
> me still.
>
>    I would find it tremendously useful if, perhaps as a part of the 
> documentation, there were several sample .org files, at various levels 
> of complexity (features used) _along_ _with_ a quick and simple screen 
> cast of its features being used in a real-life scenario. ( I find it 
> most useful for such screen casts to display key presses as they occur 
> ... is there a "plugin" which would 1) show the keys being pressed and 
> 2) also show the resulting functions being invoked by those keystrokes? 
> ). Repeatedly I've spent more than an hour trying to figure out what 
> happened when I haven't noticed that by mistake that I've pressed some 
> weird key combo which has placed my orgmode/emacs session in an 
> incomprehensible state - e.g. narrowing a buffer. Had I known which keys 
> I had pressed by mistake, or at least the functions that they involved, 
> I could have looked up the manual to see how to "undo" such mess. But 
> when you don't know that your state is being called "narrowing buffer", 
> you have no clue what just happened and that you should find out how to 
> "widen" it again. ( That is very, VERY frustrating for an emacs/orgmode 
> newbie. Someone please advise how to turn on a log of keystrokes and 
> functions being invoked by those keystrokes. ... Consider having this on 
> as default for newbies. )
>
>   It seems to me that to get people started without unnecessary 
> frustrations, we might want to put into the docs something like:
>
> To include feature : timestamp-based unique IDs : Configure emacs thusly 
> : <insert a patch here perhaps with a video/screencast showing manual 
> insertion> and then see how this works <a video here>; ...  same for 
> features like  HTML export, literal programming, custom timestamp 
> (perhaps with down-to-seconds resolution) custom, etc
>
>   I believe if I saw in a few screen casts how the orgmode 
> "professionals" use orgmode, and had access to their sample orgmode 
> files which I could follow along and literally identically modify during 
> the screencast, I would be much father (and perhaps even happier) with 
> the use of orgmode. I think the most crucial point for newbies is being 
> able to literally follow the screencast along, perfectly replicating the 
> screen cast results in their emacs / evil / spacemacs setup.
>
> If people would want to send me URLs for their sample .org files for 
> which they also have a demo screen cast on how to use their features, I 
> would like to pull these together and create a section for the docs with 
> these.
>
>   Guys! You are a wonderful bunch and you are perfecting an amazing 
> software! ... Let the world get more of a taste of your amazing work.
>
>    Thanks so much for orgmode!
>
>      John