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(a)opensuse.org
To contact the owner, e-mail: yast-devel+owner(a)opensuse.org