diff options
Diffstat (limited to '2021/talks/tech.md')
| -rw-r--r-- | 2021/talks/tech.md | 84 |
1 files changed, 84 insertions, 0 deletions
diff --git a/2021/talks/tech.md b/2021/talks/tech.md new file mode 100644 index 00000000..c327181d --- /dev/null +++ b/2021/talks/tech.md @@ -0,0 +1,84 @@ +[[!meta title="Creating technical API documentation and presentations using org-babel, restclient, and org-treeslide"]] +[[!meta copyright="Copyright © 2021 Jan Ypma"]] +[[!inline pages="internal(2021/info/tech-nav)" raw="yes"]] + +<!-- You can manually edit this file to update the abstract, add links, etc. ---> + + +# 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 +textual descriptions. + +In recent projects, I've started to turn to org-mode as the primary +format to maintain technical documentation, as well as slides for a +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. + +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 + +- 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 |