So into the wiki idea, add approved revisions - that way you get the benefits of wikis with some versioning and publishing. On Dec 17, 2011 9:52 AM, "Mateusz Łoskot" <mate...@loskot.net> wrote:
> 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 >
_______________________________________________ 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
