Hey Morten, This looks like an interesting idea. Is (a) doable in three months? It might be tricky, especially with the current state of Julia's web tooling.
I recommend taking a look over the Docile and Lexicon packages – Michael Hatherly has made really great progress with some of these ideas, and you might be able to get involved over there and figure out some more detailed ideas. Cheers, Mike On Tue, 15 Mar 2016 at 18:10 Morten Piibeleht <[email protected]> wrote: > 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 >
