On Tue, Jan 13, 2009 at 4:02 PM, Waylan Limberg <[email protected]> wrote: > Personally, I don't care for this approach. But then I'm not following > Gitorious' model of multiple repos per project. I went with something > similar to github or bitbucket. But then I'm not going for providing a > hosting service for public use either.
The problem with that is that you'll end up with loads of almost exactly similar wikis, which may or may not have some subtle differences between them. The result is that noone bothers to look at them. But I can see the reasoning behind the approach "I can clone any repository, why not the wiki too?" I just not agree with the practical results of having it that way. Anyone making substantial enough changes to his clone's wiki is likely making enough changes to the software that he's considering rebranding the software. If not, all the (wiki) changes is relevant to the project as a whole. > The way I did it is that each repo (or possibly each branch in the > future) has it's docs/wiki stored in a ``docs/`` directory within the > same branch as the code. That way, as long as the dev keeps the docs > up-to-date with his code, the docs will always match the code in that > branch/repo, If another dev working in a separate clone of the project > adds a different/new feature, then s/he can keep that clone's docs > updated. That way there's no question about which part of the docs > correspond to which variation of the code. And if 2 are merged, then > the docs are merged as well. No special repos or special branches > which need to be maintained separately. And the docs are easily > packaged up with the code for distribution. I almost went with a similar approach at first myself, my main mental stumbling blocks where: 1) I wanted it to be editable through the web. More often than not I can't be bothered to clone a repository locally, make the change, submit requests for upstream merge if it's only a small spelling fix. 2) Everyone may not enjoy having everyone able to commit to a blessed directory in the repository. The main intent is not so much proper traditional documentation, but hopefully more useful to people wanting to elaborate on a feature idea or collecting random things that may or may not be up to proper standards when it comes to documentation. Being able to clone a local copy of such a wiki into pure text and munge it into proper documentation that suits a projects standards is more valuable as I see it. >> somedays: >> * selectable format (markdown/textile/wikidoc et al) > > This is a must-have IMO. Noted. >> There's also a script/create_wikis that will create the magic wiki for >> each registered project, and search through the master tree for a file >> matching /readme(\..*)?/i as the initial content for the wiki home >> page. >> > > Personally, I think the README should be on the overview page. The > wiki home page could either be a directory listing of the wiki's root, > or the contents of ``index\..*`` depending on whether the index file > exists or not. Actually the same could apply to any subdirectory as > well. At least that's how I did it. Hey, it has worked for Apache for > years. It's more intented a starting point so it's not completely empty. But we should definitely look into integrating existing READMEs more easily into the project description (which is kinda redundant) > -- > ---- > Waylan Limberg Cheers, JS --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Gitorious" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/gitorious?hl=en -~----------~----~----~----~------~----~------~--~---
