Hi Karl, "Karl O. Pinc" <k...@karlpinc.com> writes: > > As long a your messing about with the documentation > attached is a 1 page (or 2 if you want to keep reading) > doc on getting started with emacs. If you feel it would > be helpful to include (somewhere), please do. > > I'll license it in the public domain, or gplv3, or whatever > you think might get it into the most visible place/package. > > I'd be happy to redo in RST (or docbook v5) to support > multiple formats. > > Feedback on content is also welcome. >
Thank you for your enthusiasm and desire to make Emacs more approachable! For the documentation you've proposed to be relevant to this bug, it would need to be part of upstream Emacs documentation, so that's one option. A notable barrier to this avenue is the Developer Certificate of Origin, and the potential issue of attributing copyright to the FSF, but that said, it's a good option. At this point I'd use whatever source format you're most comfortable with; later, if you wanted to upstream your work, you'd contact upstream, ask where they think it would "fit" into the existing upstream docs, convert it to the format used by the rest of upstream Emacs documentation, and submit a patch. I was able to find two web pages with good "First Steps in Emacs" type documentation, so I agree that there's a need, and that there are also other people who are interested in solving this problem. It might be worth collaborating to share data on pitfalls that new users experience, and the "many eyes" approach helps to defend against "paradox of knowledge" type assumptions made while writing documentation. To take this path, host a git repository of your project, write a README with clear objectives, of course share what you have, and reach out to forums and people who seem like they might be interested. If your intent is to eventually upstream the Quick Start Guide, please include this fact in your README, along with links to what is required. eg: all significant contributors would need to be willing to attribute copyright to the FSF and comply with their DCO checks. Ideally it would also be nice to see footnotes and/or links to existing documentation to provide direction for further growth for a new user who has succeeded in their first steps. It's also a challenge to find the balance between not enough info, and too much info, but I agree that a simple guide is a good idea, because it provides fast positive feedback that encourages further learning. I also think that the "Emacs Tutorial" could use some edits, to communicate the value of its approach. Eg: The "why", and for example I remember feeling that the cursor movement section was neat, but anachronistic, and I didn't see why it was worth learning until many years later. I sometimes wonder if Emacs' existing documentation is a form of gating, if it's purposefully designed as a "quest", or of the "paradox of knowledge" principle is in effect. It's high quality documentation, but yes, I agree, whatever the cause may be, it could be more approachable and discoverable. In addition to the Debian Emacsen Team mailing list, here are links to other forums where you may be able to find collaborators and/or people who are willing to provide feedback: https://www.emacswiki.org/emacs/EmacsForums Of course, it's also completely acceptable to work on it alone! Personally I prefer team work, because it encourages me to continue working during times when I lack motivation ;-) I hope this email finds you well, and encourages you! Best, Nicholas
signature.asc
Description: PGP signature
