Writing docs sucks! Quirkshop

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.

Concerns

  • Making sure the audience feels comfortable working in the hackmd.

Agenda

  • 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

  • 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?

  • ⚡ 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

Collaborative notes

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.

What project has your favorite docs?

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.

Documentation as a way to build community

https://opensourcesurvey.org/2017/

Pick your p☠ison: \(T_EX\), M⬇, or RST?

Choose a team below

Team Markdown

@tonyfast, @asmeurer, @isabela-pf, @goanpeca, @marslee

Team RST

@dharhas, @juanis2112

Team TEX

@melissawm,

reStructuredText vs. Markdown for technical documentation

Modern sphinx for docs and blogs.

Deploying to readthedocs and github pages.

readthedocs

github actions

  • Create a workflows folder with a deployment action. This may be able to be found on the Github Marketplace. (Deploy to Github Pages and Deploy to Python are options).
  • Now that we've selected the actions, set up how the actions are triggered. Ex. schedule to run every day at midnight.
  • We're using ubuntu-latest for the demo. It's the fastest right now.
  • Set up environment, install dependencies, script to pull the source of the docs (hackmd for our example), tell it what branch in the repo to build from.
  • Note: GitHub Pages uses Jekyll. Have to add a nojekyll file to avoid that if desired.

github pages (really easy)

Before the event

  • Launch binders
  • Restart machines
  • Which service do y'all want to use? Jitsi is the default.

Notes from the prior event

  • 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.

During the event

  • 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.
Select a repo