On Thu, Nov 06, 2014, Carsten Haitzler wrote: > i thought i'd start this here for a wide audience. > > documentation for efl. it's rather horrible. and yesterday it dawned on me... > it has license problems too. > > 1. license problems: > > the documentation in many parts is lgpl - and that means copying any code from > code snippets or examples in the docs makes the app you copy it into lgpl. > that > is BAD. enforcing the license even though with lgpl we intend the library > boundary to be the library itself. we can add exceptions, but splitting docs > out might actually be best. reality is that no one is ever going to sue over > this and it's safe as it's not intended to be a problem, but strictly/legally > it is. if someone has a legal department that really dots their i's and > crosses > their t's... they would spot this.
A related discussion: https://lists.debian.org/debian-legal/2008/06/msg00012.html Fortunately, examples are most often separate files with short modification histories and only a few authors total. Relicensing shouldn't be a huge pain of tracking down everyone. Also, since they're separate files and works, they might not even be LGPL or anything but full-copyright. > 2. our docs are a mess. a lot are not linked to and undiscoverable. they have > typos, missing docs - often are sparse and with little or nothing in the way > of > binding things together. they are at best a very slim reference set for apis > with little besides that. some references are good, but most are also very > thin. keeping docs totally in the hands of core devs (always in the source > tree - src commit access needed) simply is *NOT WORKING*. devs work on code. > we > just are not doing docs. we should do them, but reality is we are not and have > little incentive to do it. core devs are busy enough as-is. Definitely agreed. Making the glue with doxygen between the various API pages is fine once you've done enough doxygen but wiki or something similar might be better for glue (and intros and tutorials and ...). For the tutorials and the likes, better to wait a bit before starting to work on these. > 3. eo brings the added problem of needing docs to cover multiple languages > from a single source. C, C++, Lua, JS, Python... it's a unique problem that > using doxygen is never going to solve. we need a solution. i haven't found > another solution and to be honest ours will be custom due to eo/eolian anwyay. It's not terribly pretty but having no documentation in the bindings is acceptable imho. Put a link at the top of each of their API ref to the documentation for the C code, and stop there. The bindings are so close to 1:1 that they're easy to understand. > 4. people ask questions on efl all the time and we answer in email, irc etc. > .. > and this information is not captured. it's lost. that's because there is no > "forum" for asking such q's. we should closely tie such forums and q&a to > documentation. this would massively improve the value of docs. > > 5. the theory of keeping docs with the code is just not working. it doesn't > encourage them to be good. it just isn't working - plain and simple. it's time > to re-evaluate that. Again, agreed. > [...] And the rest sounds good but that's a large proposal so needs time to check and think about it. -- Adrien Nader ------------------------------------------------------------------------------ _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
