coapp-developers team mailing list archive

[Adam Baxter <voltagex@xxxxxxxxxxxx>]

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" <mateusz@xxxxxxxxxx> wrote:

> 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
>
> _______________________________________________
> Mailing list: https://launchpad.net/~coapp-developers
> Post to     : coapp-developers@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~coapp-developers
> More help   : https://help.launchpad.net/ListHelp
>