---
layout: event_detail
title: Improving the documentation
event: athens2015
order: 50
permalink: /events/athens2015/improving-docs/
---

*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**