On Thu, Jun 6, 2013 at 5:14 PM, Ali Lown <a...@lown.me.uk> wrote: > Angus has been helping migrate + update the information from the > waveprotocol site over the last few months. >
Is the plan to migrate everything from waveprotocol site to the apache wiki, or will some docs remain there? 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. > I think this could be a bad idea. Remember, I'm only proposing to move *code-related* docs to the code repository, and not *all* docs. This distinction is important. Positive points if using the wiki for code-related docs: - You have to register in the wiki just once. - You have to find someone to ask for editing permissions just once. - You have an easily accesible WYSIWYG editor. Negative points if using the wiki for code-related docs: - The further the docs are from the code, the more likely they are to grow out of sync. - I can trivially 'grep' through the code in order to rename a configuration variable. But then I have to take one additional step and search through the wiki in case it's mentioned there, note it down somewhere, and when/if this rename commit is finally shipped, I have to remember to go to the wiki to finally update the doc. - It's difficult to point future users/developers to the appopriate version of code documentation. Let's say the WIAB v0.4 README file links to http://wave.com/build_instructions. Two weeks later, the instructions are improved. Four weeks later maven migration is finished. Now whoever downloads WIAB v0.4 will follow the README link, and try to build using maven instead of ant. After extremely confusing first moments, he may or may not find out there was a migration from ant to maven. He then may bother to search for the release date of v0.4, in order to correlate it with the wiki historial. And even then, he most probably will end up the first doc version, and not the version improved two weeks after v0.4. >From my point of view, the final balance is that it's much better to use the repository for code-related docs. -- Saludos, Bruno González _______________________________________________ Jabber: stenyak AT gmail.com http://www.stenyak.com
