diff options
Diffstat (limited to '2021/talks/tech.md')
| -rw-r--r-- | 2021/talks/tech.md | 52 |
1 files changed, 50 insertions, 2 deletions
diff --git a/2021/talks/tech.md b/2021/talks/tech.md index d091d132..c327181d 100644 --- a/2021/talks/tech.md +++ b/2021/talks/tech.md @@ -8,6 +8,10 @@ # Creating technical API documentation and presentations using org-babel, restclient, and org-treeslide Jan Ypma +[[!taglink CategoryOrgMode]] + +[[!inline pages="internal(2021/info/tech-schedule)" raw="yes"]] + The emacs org-babel package is often mentioned in conjunction with literate programming. The ability to mix code segments with prose indeed offers an intuitive way to augment semantic code pieces with @@ -22,6 +26,42 @@ sure that the documentation and slides are never out of date. The session will show how leverage org-babel, restclient and org-treeslide to write and present technical documentation with style. +# Discussion + +Pad: + +- Q1: Sorry if you already answered this somewhere (but if not, can + someone with a reddit account copy this over? thx). Hi, I would love + to move my team over to using something org-based, but that'll + never happen because, well... (wait for it) Emacs! By the way, I'm + currently using heavily customized Sphinx setup, mostly internal, + sometimes shared with data partners; lots of schema-gen from message + protocols defined in code, etc. Anyhow: questions. Do you work with + non-Emacs users? If so, how did you get them to accept this + workflow? And if it's just you DJ'ing, how do they weigh in when + they want an update, open a formal ticket? +- <https://github.com/jypma/emacsconf2021/blob/master/presentation.org> + +BBB: + +- Have you encountered any push-back from people requesting the documentation who are of the opinion that only a Word document will do? + - Jan: Not really, I tend to deliver the PDFs only. If more is needed, I expect I'd make a docker container with emacs in it, so people can export the org-file to PDF themselves. + - The main problem I have is that effectively they end up branching it in order to use Word's change tracking, and there is no reverse path. + - Jan: That sounds more like a team thing. Most people I interact with are developers, and are OK reading/interpreting change tracking as a git diff, e.g. on github or azure devops. + - OK, thanks. I think that is the root of my problem I just thought I would ask in-case you had encountered the same. Thank you for the talk. + - Jan: I think in your case I'd either introduce them to a nice web-based git interface (org-mode looks fine usually), so they see it can do similar things as word change tracking. + - Jan: Thanks for your feedback :) feel free to reach out if you want to chat more. + - Unfortunately in this case they refuse to use anything that isn't a WYSIWYG interface. So even a Markdown editor in a split screen with a preview window is not accepted. + - Thanks! + - Jan: Hold their hands, be kind, small baby steps :) + +IRC: (nick: jan-ypma) + +- I use restclient everyday, but never thought about using it from code blocks, duh! Very interesting talk! +- This is a good demo, I've found org-babel to be a really amazing glue language for stuff that's sort of annoying to automate otherwise. +- Thanks! :) So the fonts of the current talk are: Fixed pitch (serif): New Heterodox Mono, Variable pitch (serif): ETBembo +- for live coding presentations, demo-it is also pretty cool +- indeed, i have been trying to work out literate devops through org documents. Very cool and useful in specific contexts atleast I guess. like finding the status of a service quickly right within a structured org document. # Outline @@ -30,7 +70,15 @@ org-treeslide to write and present technical documentation with style. - Demo: REST API guide - Demo: Presentations - Used packages and configuration - -[[!inline pages="internal(2021/info/tech-schedule)" raw="yes"]] +[[!inline pages="internal(2021/captions/tech)" raw="yes"]] [[!inline pages="internal(2021/info/tech-nav)" raw="yes"]] + +# Speaker profile + +Jan Ypma is an independent software architect and developer, specializing on the Java platform, functional +programming and distributed systems. + +Name pronunciation: Jan EEP-mah +Pronouns: he/his +Preferred contact info: jan@ypmania.net |