I would like to put together a GSoC proposal targeting the documentation. Some thoughts have been on floating in my head as I have been using Julia for the past year and would be fun for me to work on.
Specifically, the following could be specific enough the be a GSoC project: (a) A system for user notes/feedback on the docs. The idea is to have a system where the users could comment on every section of the documentation, probably also with a moderation system in place. Basically inspired by the PHP documentation, where every page (e.g. function) has notes attached. It would effectively make the docs update and improve more rapidly, by people sharing their thoughts and examples on particular functions, types etc, and on the other hand make it easy for others to find. These entries would complement the documentation, or function as a temporary placeholder documentation, if the documentation is lacking something. It would also offer a library of use cases etc. for people who would at some point hopefully edit the official documentation, helping to write better documentation in general. For the implementation, it depends what’s out there of course. Perhaps something existing could be tweaked for to fit Julia, Read the Docs extended or something written from scratch. (b) Automation tools & guidelines for the docs This one is a bit more vague, but would involve making the docs even more friendly to automatic parsing and then making use of that. For example, creating useful, thorough reference manuals for packages (like the Base has, but I haven't seen for packages). Moreover, even the Base could benefit from having more thorough information (e.g. exact function signature, automatically extracted from the code). Part of it would be figuring out and defining a good way to write documentation for packages, so that it could be used be automatic tools for displaying etc, and also how to display it in a useful manner. What I have in mind is something like doxygen or javadoc for Julia. I think it could also tie into the only documentation-related idea on the ideas page regarding having docs in the IDEs (under Juno). Would love to hear whether people think that these could be a useful and one of them make a reasonable GSoC project (and if so, whether there’s anyone willing to mentor it). Also, just to hopefully start a useful discussion, what other thoughts have people had to make the docs even better? Best, Morten
