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