Bruno, Sorting out the documentation is a great way you can help.
Angus has been helping migrate + update the information from the waveprotocol site over the last few months. We have been putting all new documentation in the wiki here, since it is the easiest place for it to all be found and edited when it is out-of-date. I would advise against putting documentation directly in the code repository (other than the notes written by developers as the code is written), as it is likely to get updated less often there than if we agree to keep it all on the wiki. [Though the ultimate guide to what will happen is the source code!] It would be good to reduce the README down to just "Thank you for downloading Apache Wave.\n For installation please refer to https://url/install.\n For licensing please refer to LICENSE and NOTICE", rather than the installation guide it seems to have turned in to. The server-config.xml description tags (and the comments in the src/org/waveprotocol/box/server/CoreSettings.java are there purely as reminders to the developer as that bit of code is written. (And until the documentation gets updated)). Similarly, for the comments in various scripts, but it would be good to create a page for each on the wiki explaining their use then update the script to include a 1-line description and a link to the wiki. Ali On 6 June 2013 15:57, Bruno Gonzalez (aka stenyak) <[email protected]> wrote: > Hi all, > > I see that there's bits of documentation here and there, sometimes it's > duplicated in several places: > - Source code (README file, server-config.xml description tags, comments > inside sh scripts...) > - Confluence wiki at apache > - WaveProtocol.org site > (not sure if I missed any place else?) > > This can be a bit confusing, so I suggest deduplicating the > documentation. If more people agree with this point of view, I offer myself > for the task. > > > My suggestions would be: > - Keep docs closely related with code, in the code repository. This > prevents version mismatching. E.g. how to build the code, how to configure > it, how to run the server... > - Keep the rest of stuff in the confluence wiki. This is stuff that will > change very rarely. E.g. whitepapers, FAQ, generic user-facing > information... > - Remove all duplicated docs from waveprotocol.org site. and point to the > apache wiki (I'm not sure what's the actual status and purpose of the > waveprotocol site?). > - Whenever something is moved from the apache wiki to the code repository, > provide a link to a browsable version of the relevant repo file. E.g. "For > more info, see https://github.com/apache/wave/blob/trunk/README";. > > > Please voice your opinions. If nobody opposes in the next few days, I'll > start working on it. All suggestions are welcome :-) > > > -- > Saludos, > Bruno González > > _______________________________________________ > Jabber: stenyak AT gmail.com > http://www.stenyak.com
