This quirkshop is a panel that explores the value of community, content, and format for open source software. Documentation is for the community so today we’ll work together to take notes in hackMD. These notes will become documentation for today’s quirkshop on read the docs and github pages.
Github: https://github.com/Quansight/quirkshop-docs
Youtube: https://www.youtube.com/channel/UChdlbCpQ_Wep04V9o0sGLWQ
Jitsi: https://meet.jit.si/quansight-quirkshopdocs
Dial-in: +1.512.647.1431 PIN: 2558 9397 79#
Readthedocs: https://writingdocssucks.readthedocs.io/en/latest/
Host: @ftarlaci
Guests:
@asmeurer
@melissawm
@goanpeca
@juanis2112
Making sure the audience feels comfortable working in the hackmd.
Prelude: (:05)
@fatma will leads us in and welcome the internet to the quirkshop
remind folks of the hackmd for taking notes. writing documents together makes us better. we’ll publish these after the meeting.
There is a section to place your github name in which documentation team your on (latex, md, rst).
Introductions:
Name, Location, Role, Projects you work on.
Rants/Raves
What project has your favorite docs?
Write the docs
Any docs with good visual aids
Python docs
Mozilla Javascript Docs
Docs for visualization tools with good gallery views (like matplotlib)
Django docs
Django girls
pymotw
Panel (:12)
Quansight labs and docs
Posts
@juanis2112 Writing docs is not just writing docs
What’s the goal of your docs? What are you trying to help with?
how can you be empathetic with the user?
@melissawm Documentation as a way to build community
documentation is like writing educational content.
documentation is critical to adoption.
good place to do high impact work.
how to’s, tutorials, explanations, api reference.
This blog post has a focus on the process Melissa experienced while working on NumPy docs
Themes
Who writes the docs?
User and developer writers developing docs. They have the best understanding of what other people likely need to do and have questions on.
Risk of missing things that new users or people with less experience if it is written by a developer who has a lot of experience. It is easy to make the wrong assumption about how much someone reading the docs already knows.
At the same time, maybe developers have a responsibility to write docs because they might be the only people who can share their high-level understanding and help others gain that knowledge.
Who should actually do it… and why?
Underdocumented projects have a bad look. How do developers relate to users across a literacy gap.
Train developers to write documentation.
How does project size influence docs?
Amount of developers
type of project.
not all project are born equal.
fast vs slow documentation.
fast projects are unstable
slow projects are stable
Whether or not there is a set process for writing the docs. Bigger projects might have protocols where smaller don’t. Both options can be an obstacle.
@asmeurer experts struggle to write introductory documentation.
Why is documentation considered a “first good issue?”
We were just talking about needing a strong understanding of the project, but do people new to the community know that yet?
Can be good for catching areas that are topical to new users and easily overlooked by long term development.
Size & scale
Who still knows all of numpy?
Folks focus on subject areas.
Reviewers that understand
Biweekly meetings of 8 or 9 people.
Create issues requesting content.It’s helpful to create priorities for the people currently writing docs.
Idea that because you aren’t writing code it is technically easier, but that can be misleading. Bad docs create problems long term.
Docs are usually the face of a project. Might be the first things users see.
Finding new documentation contributors: ownership, credit and open source
Documentation programs
Google summer of code is not google season of docs. GSOC is older
Google season of docs.
not google summer of code
Pros and cons :-) ?
Grants don’t allow the use of money for maintenance and docs.
September–December timeline, pairs technical writers with projects
styleguide? good idea.
Technical writers tend to have skills that are often missing in a lot of communities and can help with things like organizing docs more consistently or building a style guide.
CZI EOSS
Docs aren’t often funded, so programs like this can be critical.
Content is king.
In the absence of resources, what type should documentation content should be prioritized?
Four kinds of documentation
reference documentation is critical. Probably won’t get written unless the developers on a project write it.
Other opinion is tutorials. Helps you get started. If they get a bad first impression, why would they continue with the project. If they know the basics they are in a better position to find more docs later.
It depends on the goal of your project. Is the project only meant to be for users trying to learn to use a tool? Is the project looking for people to contribute code and need to give a good technical background?
What about tutorials or Stack Overflow questions? Are these a kind of docs not written by the project itself?
Documentation is best when it caters to a variety of literacies. Maybe that approach should be kept in mind from the beginning.
Pick your p☠ison: \(T_EX\), M⬇, or RST?
reStructuredText vs. Markdown for technical documentation
⚡ talk: Modern sphinx for docs and blogs.
@tonyfast One conf for your docs and blog.
myst, jupyterbook, Troff :-P Who did this?
Deploying to readthedocs and github pages.
@goanpeca :-) CI and Github Actions FTW!
questions
outro
Exit survey
We encourage the audience to work together in taking notes about the highlights and important resources shared during the panel. We appreciate everyone pitching in to make some nice docs together that we can be proud about when the presentation is over.
Any notetakers, please add your faves too!
Matthias : You did not specify Python Only, so I’m going to say Rust, docs.rs, thy have a bynch of fancy stuff, like for example all example are guarantied to compile, or have a orange/red border if they are purposefully invalid. It’s also out of the box, no configuration needed typically. They also rebuild docs for all the new crates uploaded.
https://opensourcesurvey.org/2017/
Patron saint of yakshaves
@tonyfast, @asmeurer, @isabela-pf, @goanpeca, @marslee
@dharhas, @juanis2112
@melissawm,
Readthedocs configuration file
Launch binders
Restart machines
Which service do y’all want to use? Jitsi is the default.
I think there should be reminders by the presenters about turning off mics to prevent echo.
Be mindful of what the viewers are seeing on shared screens …It would be best if that clicking around and scrolling were done “off camera” and then only shared when the appropriate thing was on screen.
I really liked this overlap of two seemingly disparate skills that combine in one application.
Links are good. Appreciated the CSS gif and links to what’s beyond the quirkshop’s scope, such the CSS art, for people that are interested in reading further.
Sometimes it was confusing or cluttered when the presenter’s sreen included their Jitsi screen over the demonstration.
The current Binder link that automatically splits Binder and Jitsi for participants is great and should be continued.
Be yourself. We 🤍 you cause you’re you.
Minimize videos number of webcam shared in jitsi.
Children and animals are welcome interruptions, social norms during covid are different.