2011/12/16 Garrett Serack <garre...@microsoft.com>: > Well, since I'm going to spend the next week or so writing docs, I'll start > by chiming in. > > The wiki's not a bad place to start (GitHub's wiki is Markdown, so that's a > good thing).
GitHub Wiki is great. My concern is about using Wiki in general as a first-contact documentation. Wiki seems great for brainstorming, related but not required material, collaboratively created material, etc. My main concerns about Wiki for docs: - high potential of chaos - documentation is static by nature, Wiki is very dynamic organism - it is easy to add new content (strength) and screw beauty of order, and make mess (weakness) - with dynamic and floating content, maintenance may be a hassle: need for constant review, find what's not up to date, remove or move to deprecated section, etc. - may not be friendly for other output formats (PDF, ePub) I'm sure everyone has seen crap documentation based on Wiki-like docs, especially in Java world (Atlassian, JIRA) with complete chaos (e.g. old docs for Hudson, now Jenkins CI). > But I think since it's so easy to write Markdown, (and we can add images, > etc) we > should just start creating pages in the coapp.org github project, so that the > stuff that's > being written is first available for the web, right on the CoApp site. The Markdown is great format indeed. I don't suggest to change. > Now, that brings up an inteheresting issue. > [...] > So, I've been looking at alternatives to jekyll, that are easier to setup (so > others can git clone, and add pages easily). That's my concern: too easy to add, too easy to make mess. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net _______________________________________________ Mailing list: https://launchpad.net/~coapp-developers Post to : coapp-developers@lists.launchpad.net Unsubscribe : https://launchpad.net/~coapp-developers More help : https://help.launchpad.net/ListHelp
