Hi, When Christopher was in Prague, a few of us had a brainstorming about the need of having devel-documentation placed directly in a Yast/libstorage/linuxrc repository. There are no doubts that it's one of the most important parts of projects hosted at GitHub. All their howtos mention "create README[.md]" as the very first step. In fact, we'll have new hires in the team and in such situations, good documentation is one of the most important parts. Good documentation goes from very high level to lower and lower level. We have already summarized that in Yast Team Challenges, but the summary doesn't belong to this document as it's too detailed. That's why I'm putting it here as a WIP item and deleting it from that document: --- cut --- The README should at least describe the steps needed for maintenance (for a person without expert knowledge in the area) including: * What is the project good for - what does it actually do (and how), what it cannot do (unsupported scenarios), limitations * Links to the documentation, high level and low level descriptions (e.g. RFC, wikipedia articles, man pages, project documentation, openSUSE wiki), terminology * How to fetch the source code (if something outside Git is needed it should be mentioned) * What prerequisites are needed to build the sources (external libraries, gems, scripts, …) * How to build the sources (make/rake commands…) * How to setup a testing environment (e.g. iSCSI target for iSCSI client) * How to run the code to test a change (esp. needed for non trivial projects like linuxrc) * How to run automated tests * How to build a package for submission * How to submit the package (if it needs some manual steps) * Troubleshooting (how to solve typical problems) The README should be reasonably short, if some section is too long it should be moved to a separate document (or to GitHub wiki) and linked. --- cut --- The project consists of - Taking a decision where to go - How to get there - Implementing this important documentation Those two who, according to my knowledge, were working on this were Ladislav and Christopher, but there were not the only ones and a pilot project for READMEs has been done a few months ago by Martin. It's still not finished, but moving forward. Thanks Lukas -- Lukas Ocilka, Systems Management (Yast) Team Leader SLE Department, SUSE Linux -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org To contact the owner, e-mail: yast-devel+owner@opensuse.org