diff options
Diffstat (limited to '2021/talks/tech.md')
| -rw-r--r-- | 2021/talks/tech.md | 69 |
1 files changed, 53 insertions, 16 deletions
diff --git a/2021/talks/tech.md b/2021/talks/tech.md index 4a46c629..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 @@ -19,29 +23,62 @@ technical language course. By using org-babel to pull in "live" code for REST requests, language examples, and shell scripts, one can be sure that the documentation and slides are never out of date. -Two cases are presented: +The session will show how leverage org-babel, restclient and +org-treeslide to write and present technical documentation with style. -- API documentation for a REST service (exported from org to html - and PDF) -- Slides for a Java Microservice course (presented within emacs, - handouts in 2 styles as PDF) +# Discussion -The session will show how leverage org-babel, restclient, -org-treeslide, as well as show how to create your own language backend -for org-babel to make sure your own preferred workflow is used. +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: -# Outline +- 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 :) -- 5-10 minutes: We'll pick one of the two use cases and briefly show - it and its result. -<!--- 20 minutes: We'll briefly show both use cases. -- 40 minutes: We'll show the details how to combine the mentioned - packages, as well as showing the custom org-babel backend. ---> +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. -[[!inline pages="internal(2021/info/tech-schedule)" raw="yes"]] +# Outline + +- Introduction +- Demo: Developer guide +- Demo: REST API guide +- Demo: Presentations +- Used packages and configuration +[[!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 |