coapp-developers team mailing list archive

[Mateusz Łoskot <mateusz@xxxxxxxxxx>]

2011/12/16 Garrett Serack <garretts@xxxxxxxxxxxxx>:
> 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