Improving the documentation

45-minute session on day 1

Let’s try to find aspects that are missing or could be improved in the documentation currently available on reproducible-builds.org website.

• Good/bad practices for an upstream, what should it be aware of? (e.g. toolchain recommendations)
  • available
• Checklist for developers
  • available
• What about distro-specific documentation? Roadmaps for distributions (step-wise: once you got to X you could do Y and so on)
  • partially written: as many projects are making their own experience it’s hard to have good answers now.
• Documentation for non-free software toolchains and platforms that might not be able to go for the bit-by-bit paradigma.
  • available, at least basic ideas.
• Documentation for people that tried to reproduce a program but failed (being that they get different output or the build is falling at all). What are the next steps in this scenario?
  • missing
• Step-by-step help with common problems (screencast + example by step)
  • missing
• Index by tool in order to show you easily information/issues with/about it and how to resolve them. “If you use this tool, these are the things you need to think about”
  • missing
• Contact opportunities/getting connected information on the website (mailing list and/or IRC channel)
  • available
• Slidedeck for someone running a class with motivation/pitfalls/solutions
  • missing
• How do you set up an automated test environment
  • missing
• Standard slide deck for university lectures (add exercises)
  • missing
• Document how to contribute to the website
  • missing