4 ms·
Conversely, I don't even use open source software that doesn't have a simple README on Github showing me plentiful examples on how to use the damn library. Sor
by Swizec 14y ago
Conversely, I don't even use open source software that doesn't have a simple README on Github showing me plentiful examples on how to use the damn library.
Sorry, if you don't have documentation, even a little bit, you're just not worth my time. There are at least two other libraries out there with better documentation. The fact they might be worse software doesn't even matter because all I'm looking for is a solution.
- exDM69 14y agoGitHub READMEs are an excellent compromise. Doing more detailed docs are quite a lot of effort (that is better spent coding), especially to projects that are at an early stage. Projects which are an early stage (like most of my projects) should mostly try to attract potential contributors, not just consumers/end-users so it's not unreasonable to require would-be users/contributors to walk the extra mile and actually read (at least parts of) the source. I do that even for projects that are well established with docs if I intend to depend on them. If there actually were libs that are well documented and do the same thing, I wouldn't have started the projects I did but contribute to the existing projects instead. This may not be true for all kinds of projects.
- rgbrgb 14y agoThere's a double standard here. You want developers to contribute to your project despite the lack of documentation but you require that libraries you contribute to are well documented.
- exDM69 14y ago> ...but you require that libraries you contribute to are well documented. You misread me. I almost never read the docs because they suck more often than not. I start from example and test source code and almost always end up reading parts or most of the source code.
- rgbrgb 14y ago> If there actually were libs that are well documented and do the same thing... I thought you were implying that you required libs you contribute to to be well documented.
- dredmorbius 14y agoEven very early alpha code can find its way into production systems. I'm familiar with a case involving a three-letter household name company a few years back using early releases of cassandra, as well as nginx (not entirely beta at that point, but with much of the documentation still in Russian). Engineering making it work was a long way from operations making it reliable and understood.
- just2n 14y agoThis is an understatement. Even if Github is just a place to put your toy library/project and it's not being promoted, there should be an awesome README showing off what it is meant to do (even if it doesn't do that yet, just point out that those features aren't yet available). When I find engineers on Github who've contributed to projects I enjoy using and I look through their repositories to find projects with interesting names but NO README, I get annoyed. I don't mind reading code, but sometimes I just want to see what this thing does before I go about reading 2 thousand lines of code. The worst thing that could happen is that someone would want to start using your library while it's in an alpha state, and then complain that it's not perfect. But in the end, if people would really find something you're working on useful, you might get a lot of community support and motivation to finish it, so why not? And as you state, when features are completed, there should be pages with ample examples on how to use them. Programmers can usually read a code example ten to a hundred times faster than they can read over the documentation for everything used in that example, and in well written code, the expected functionality (that is: documented behavior) is clear from an example alone. Programmers can also write a quick code example with a few inline comments faster and better than they can write good documentation.
- sophacles 14y agoGood for you. Don't use my open source stuff. Turns out I wrote it for me, whether you get anything out of it or not doesn't actually affect me. If you do get something out of it, great. If you contribute great. But unless you are paying me, don't tell me what I should be doing with my hobby time. Period, end of story, full stop. Take your demands to someone else. Further, demands for great documentation are unreasonable. I can point to hundreds of examples of 'well documented' projects where I still dig into the source code and do simple experiments to learn what the heck it does. This is a combination of how I learn and how I use software. Your docs (for all values of you) are crappy and don't tell me how the software works - the code does that tho, so I actually can trust it. If you want to do truely great documentation, put some comments of expected use at the top of the function/class/whatever definition, some comments on tricky sections of code (not "this does the file read" i get that from the call to read(), but "this also triggers an event from the OS handled in foohandler()), and good clean loosely coupled components.
- irreverentbits 14y agoYeah, see, here's the thing: for many projects of noteworthy complexity, it'll be easier to gain an understanding of how to make use of it through a clear set of docs than it will be by slogging through source code. Good documentation provides context and use cases. Good comments in source code provide clarity as to what the code is doing. They are in no way equivalent. One of the benefits of encapsulation in software is that it enables individuals to program against a documented interface without spending (although in many cases I'd say wasting) time to understand the intricacies of implementation. You lose that benefit if you're forced to dip into code to understand how to use that code. You do have a point, though - as an open source dev, it's your time to spend as you see fit. But a quality open-source project is more than the sum of its code.
- ZoFreX 14y ago> You do have a point, though - as an open source dev, it's your time to spend as you see fit I agree with both of you - I don't see software as "complete" unless it has documentation, it's part of the package to me. I happen to like writing it, but I hate some other aspects of programming - doesn't mean I skip those sections. However, I have put things online without documentation before, because the software wasn't complete but maybe someone else would complete it, or find it useful, or learn something from it. Maybe they won't - but I lose nothing by putting it online, and the world stands to gain.