conference notes

FOSDEM 2017

Take a look at's

• http://www.flycheck.org/en/latest/ emacs integration
• Gnu Geeks (https://www.gnu.org/software/guix/)? universal package management

[Talk] Continuous integration at a distribution level

martin.pitt@ubuntu.com

• old(break/freeze/fix) lost a lot of feedback, nobody used dev build
• feature freeze -> stuff got tossed in and not finished
• thus move to rolling release and have everything tested, stable and working at all times

Motivation

• devs of sf are responsible for testing sf

• put tests for source pkg in source pkg

• trigger tests when pkg or dep is upgraded

• look at dep8 (debian enhancement proposal 8)

• look at autopkgtest (programm they use to test)

• look at qemu (sounded like dockerish)

• look at xenial(maybe linked to qemu)

Gating

• stage new proposals into proposed(broken by definition), migration(tests are run here), devel(in theory this is stable)
• proposed migration (test request)-> RabbitMQ + AMQP server (worker/test result)-> Swift object store (result.tar)-> result browser(web ui)

Upstream integration

• ideally get your tests into upstream so they test and don't break

[Talk] RTFM? Write a Better FM

• Community is your documentation. Care for it so code and doc are also cared for

• Community > Code

• Community sets tone for docs, docs sets tome for community

• Docs are many things. Formal docs, conversations in chat, bug trackers...

• Think of users as customers (they justify the existence of your sf)

• consider the feedback loop of your community

• you attract whom you choose (jerk-y docs get you jerks)

• choose community by choosing a tone (not only copies of yourself)

Knowing your audience

• Use Personas
  • What does persona know in this step, what is the problem, what does persona need to learn/know
• Not everyone is white english-speaking male
• Inside Jokes divide the community (us/them) explain them so others can join in. Combine with above
• Be mindful of the examples you use. Some cultures might not have the sam e context you do
• Keep track of what the audience is asking. You may not know what the audience is searching for.
• Engage people where they are (chat/stack exchange)

The customer is not an idiot

• It's hard to accept they are not
  • We are brilliant
  • I worked hard to achieve brilliance
  • I do not know the context to their problem
  • I do not know their tools
• "We did hard work, you also have to do hard work, punk"
• Feeling that our work was more important than their work
• We conditioned our users to think of themselves of idiots
• "Dismissing people with a hand wave to go read the docs"
• "We as experts have better things to do than helping noobs"
• "If you don't have the time and patience to communicate with noobs, then don't"
• "Be kind, for everyone you meet is fighting a hard battle" -plato
• By dismissing them we tell them their problems are not important and relevant
• Humility
  • You don't know everything
  • The documentations isn't perfect
  • Remember that you once were a noob too
• If this is too far away, go to a new project and ask them in irc to see how it feels like
• RTFM! shows noobs that they are not welcome in our community
• Your attitude about stupid questions says a lot about you
• It's our job to guide them to the right question and answers
• Why are they asking the stupid question?
• Often the problem is bad docs
• people want solutions fast and dont think about maintainability and consequences

So what do you write?

• write a lot so you have a lot to throw away so enough good stuff stays
• Writing everyday helps (just 10 minutes every Morning)
• Decide of the scope of your docs
• Document the scope
• Decide not to answer the wrong questions but point people to somewhere
• Reference manual
  • comprehensive and exhaustive
• software changes, stay on top
• feedback loop with devs(correctness) and users(still works?)
• stay to the scope (don't cover everything too much)
• document best practices (chats are for hacks)
• Show copy paste solution and discuss the way how to arrive there afterwards
• show all the steps
• Don't ridicule your user (show solution, then say it's bad, don't use it)
• Don't tell people how not to do it
• Be welcoming of new doc contributors
  • your docs are wrong, incomplete, difficult to understand, someone knows more than you
  • make it easy for them to help you
• everyone knows everyone hates writing docs. (this is not true!)
• We make it hard for them to help so they go to stack overflow et al.

Better docs

• Lower barrier new people joining docs team

• mentor them

• encourage them to participate in the process

• But... not too easy. Crappy docs doesn't help anyone

• Find the balance

• Don't fight someone telling you your docs is bad. Doesn't help anything

  • Instead ask them to help and how it can be improved

• Add "edit on github" link to docs

• Make it easy for people to contribute to your docs

• not too easy or else there will be spam

• treat docs like you treat your code

• Add respect to docs working

• Add a comment mechanism to your docs to make it easy to add input but "hard" to get it into the real docs

• Docs are conversation

QA

• We have so many newcomers (feeling like an edu project) and are burning out on answering questions about stuff that is in the docs.
  • Get newcomer to answer the next question (I helped you, now you help the next one)
  • Get a deworded version of your guide so reading it is less work
  • Encourage newcomers to help other newcomer to build the movement of helping others outside of the dev team
  • Don't jump in as the "expert" to fast
  • Rotate mentor role to not burn out ⁻ Add motivation (as in earned respect eg) for newcmoers to answer questions
    • award a-/rewards for active helpers