Scribd
Upload
3 views

Effective_Technical_Discussions

Chapter One discusses the importance of effective planning and communication in software development, emphasizing the value of reproducible code and technical discussions. It highlights tools like GitHub and Jupyter Notebooks for sharing code, along with techniques for enhancing discussions through multimedia elements. The chapter concludes with exercises aimed at creating technical posts and fostering active learning through collaborative interactions.

Uploaded by

xZealthiusx
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
3 views

Effective_Technical_Discussions

Chapter One discusses the importance of effective planning and communication in software development, emphasizing the value of reproducible code and technical discussions. It highlights tools like GitHub and Jupyter Notebooks for sharing code, along with techniques for enhancing discussions through multimedia elements. The chapter concludes with exercises aimed at creating technical posts and fostering active learning through collaborative interactions.

Uploaded by

xZealthiusx
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 7

Chapter One: Getting Started

Ge ing started with a good plan is the most allenging part of building so ware. is apter
covers how to do that.

Effective Async Technical Discussions


What makes a useful te nical discussion? Several te niques significantly enhance a professional
conversation around te nical details.
Here is a screencast on how to create a useful te nical discussion.
Video Link: h ps://www.youtube.com/wat ?v=gcbjlq3B4cw³

Reproducible Code
If a discussion involves code, the ability to reproduce the system significantly enhances the conver-
sation. e source code that is shared or discussed must run smoothly. If not, then it could add zero
or even negative value to sharing it. Hosted git and hosted Jupyter Notebooks⁴ are two common
ways to solve this problem.

Hosted git

ree main versions of hosted git are: bitbu et⁵, github⁶ and GitLab⁷. ey all provide ways to
share and reproduce code. is code can share within the context of a so ware development project,
and it can also share in an async based discussion like at.
Let’s focus on Github, the most commonly encountered of these options. ere are two main ways
to share code with others. One method is to create a public repo.⁸ and share code and/or markdown⁹
files. One nice side effect of markdown files is that they can also serve out via webpages through
GitHub Pages¹⁰ or through a blog engine like Hugo¹¹, whi can build pages <1 ms per page.
Another powerful feature of Github is a gist¹². What is particularly useful about a gist is that it can
be shared with syntax highlighting and forma ing. Here are the steps:
³https://www.youtube.com/watch?v=gcbjlq3B4cw
⁴https://jupyter.org/
⁵https://bitbucket.org/product
⁶https://github.com/
⁷https://about.gitlab.com/
⁸https://help.github.com/en/github/administering-a-repository/setting-repository-visibility
⁹https://guides.github.com/features/mastering-markdown/
¹⁰https://pages.github.com/
¹¹https://gohugo.io/
¹²https://gist.github.com/
4 Chapter One: Ge ing Started

1. Create gist

creategist

2. Share gist
5

sharegist

3. Here is the URL to share:


Gist Example¹³
Many at programs will automatically render out the code snippet.

Hosted Jupyter Notebooks

In theory, Jupyter Notebooks solve a massive problem in creating reproducible code, but it needs
some help in practice. A fundamental limitation of Jupyter is the Python pa aging environment. It
is a helpless victim to the untamed complexity of the underlying operating system.
Fortunately, there is an easy solution. Jupyter notebooks that have a portable runtime are the
reproducible ones. Portable runtimes include do er¹⁴ and colab¹⁵. Do er format files can specify
what the runtime should be like, including the pa ages that need for installation.
One example of a hosted runtime can is in this project: Container Microservices project¹⁶.
For a user to recreate the code and run it locally, they can do the following:

¹³https://gist.github.com/noahgift/b6eec243c70ba4f71033954c4da75dd3
¹⁴https://www.docker.com/
¹⁵https://colab.research.google.com/
¹⁶https://github.com/noahgift/container-revolution-devops-microservices
6 Chapter One: Ge ing Started

1 #!/usr/bin/env bash
2
3 # Build image
4 docker build --tag=flasksklearn .
5
6 # List docker images
7 docker image ls
8
9 # Run flask app
10 docker run -p 8000:80 flasksklearn

is approa is optimized for deployment and has some advantages for communication focused on
deploying so ware. A second approa is the colab approa . In this colab example¹⁷ the notebook
note only has the complete code, but with a cli of the “Open in Colab” bu on, a user can completely
reproduce what was shared.
¹⁷https://github.com/noahgift/functional_intro_to_python/blob/master/Public_Master_SafariOnline_Day1_Part1.ipynb
7

sharecolab

Audio, Video and Images


Adding audio, video, and images can significantly enhance a te nical discussion.

Sharing images
One simple “ha ” for sharing images is to use Github issues. Here is an example of this in action¹⁸.
¹⁸https://github.com/noahgift/cloud-data-analysis-at-scale/issues/1
8 Chapter One: Ge ing Started

shareha

Screencasts
Doing a qui screencast can boost a discussion value. Here is a screencast of creating an AWS
Lambda function; this is an excellent example of a short demo video.
Video Link: h ps://www.youtube.com/wat ?v=AlRUeNFuObk¹⁹
Here is another screencast on what to consider when creating a te nical video.
Video Link: h ps://www.youtube.com/wat ?v=upQEE9jwI3M²⁰
You can create screencasts qui ly using the so ware you probably already have on your ma ine.
Options include: Zoom²¹, i Time Player²² and Camtasia²³.

Produce Once, Reuse Many


One thing to keep in mind with te nical discussion is produce once, reuse many. ere are many
outlets for a professional review, including classroom discussions, work discussions, books you are
¹⁹https://www.youtube.com/watch?v=AlRUeNFuObk
²⁰https://www.youtube.com/watch?v=upQEE9jwI3M
²¹https://zoom.us/
²²https://support.apple.com/guide/quicktime-player/record-your-screen-qtp97b08e666/mac
²³https://www.techsmith.com/video-editor.html
9

writing, or so ware projects you are contributing.


You can use these notes and code samples for years or even the rest of your life if you produce high-
quality te nical notes. Why not create high-quality comments so you can “reuse” these assets in
many ways.

Technical discussions as a form of active learning


One substantial advantage of te nical discussions is they serve as a form of active learning. Writing
so ware in a professional se ing with modern so ware development practices o en involves many
team interactions (i.e. pull requests²⁴). is is a form of “super- arged” learning that enables
so ware engineers to learn at an extraordinary pace.

Effective Async Technical Discussions Conclusions


Building so ware or doing data science is not about se ing aside a session and building something
to stop. It is an iterative form of group communication. In turning in homework assignments or
finishing a commercial project ti et, the conversation is where the most value occurs versus just
the raw so ware code.

Exercises-Create technical posts

Topic: Create technical posts

Directions

• Part A: Use the te niques described above and create one or more “te nical” posts in a at
annel like Sla ²⁵, Piazza²⁶ or Canvas²⁷. Express your idea in code using one or many of the
te niques described above.
• Part B: Comment and reply to at least one person where you learned a new te nique.
• Part C: A er the “dust” has se led in a day or two, write down and document what you learned
so you could use it.
• Part D: “Demo” your post

²⁴https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests
²⁵https://slack.com/
²⁶https://piazza.com/
²⁷https://canvas.instructure.com/

You might also like