Please include a brief readme doc/README.s5pc1xx similar to README.omap
Hi Tom, Others may disagree, but I'm personally opposed to creating
Slugfest over documentation!
Nothing gets me more worked up than a documentation discussion:)
I can see you point. If you have the board you likely have the user manual. In no way do I want a user manual.
Mostly what I am looking for brief product description and a list of the configs. Maybe some hints if the setup is tricky. README.omap3 contains writeups on 6 boards, each get about 10 lines.
The README.omap3 looks decent, but even that I would personally have a few issues with the following: 1. The list of omap3 boards is going to get out of date quickly when people don't update README.omap3. Eg devkit8000 already isn't in the list:)
2. I still think the details of how to configure U-Boot for a board, use the ecc commands, and gpio interfaces would still be better placed in a User's Manual. New users will use the User's Manual and experienced users will know how to dig through the code - eg I'm not sure who will reference README.omap3:). Those command names and config names will probably change at some point in the future, and there's a decent chance README.omap3 won't be similarly updated.
The vendor readme is also good if you want to convey board family u-boot interfaces to other developers. See my writeup of omap gpio in omap3.
I see your point. If it were me, I'd throw that documentation in the omap3 gpio driver itself. Its much more likely to be kept in sync when code changes, and if someone is writing low-level U-Boot code, I'd hope they'd be smart enough to track down the gpio driver they need to use.
board/vendor-specific doc/README.<board> files in most cases. My logic is that the people that are compiling and using U-Boot on my company's boards will have bought the boards from us, and we should be the ones providing them documentation. eg I would guess the vast majority of board vendors don't say "for board information consult doc/README.<board> in the U-Boot source code", they provide a PDF, text document, datasheet, etc about the board and how it can be used. Thus the doc/README.<board> doesn't really provide any useful info.
This is doc/README.<soc>
OK, I missed that point. SOC documentation does seem more fitting. I personally think low-level details shouldn't be in the SOC doc however. For example, take a look at README.blackfin. There's nothing I could ever change about U-Boot which would require this file to be updated, which is perfect!
<snip>
I only care because I hate having to pick through 10 board-specific README files every time I make a change the renames a command, adds a new command, changes a CONFIG_XYZ name, etc:)
This should be the task of the board/soc maintainer.
I think this is debatable. I'd guess most board maintainers don't follow the list closely or care enough to monitor every change and determine if they need to update their board's README file. So if the person making a large change doesn't update relevant READMEs, no one will. Eg, no one added devkit8000 to README.omap3.
I think README files are good in general, but board-specific details should be documented elsewhere such as a product manual.
Anyway, that's my $.02.
Taking it outside over documentation,
Best, Peter