Feedback request | Documentation site reorg, switch to Markdown

[Little Girl]

Hey there,

I'm sending my reply again because I forgot to carbon copy it to all
the other lists.

Peter Matulis wrote:

> This is a request for feedback from the community.

I thought I'd chime in on this as a fly on the wall. My vantage point
isn't as a current participator or as an expert participator, but
certainly as someone who has participated in several projects
(including Kubuntu and Ubuntu) in the past and is likely to again.

If the motivation for the change is an attempt to increase
participation, it may not work and isn't likely to be a factor in the
reason(s) for low participation. In my experience, tools aren't
usually the reason people don't participate. Most of us who want to
participate are willing to put up with minor annoyances caused by
tools we don't happen to like or aren't familiar with. Participation
usually drops off for other reasons which should be investigated
independently of the tools used in the project and some of which are
beyond the control of (and unrelated to) the project.

If the motivation for the change is to bring unity to the project,
then that's a solid motivation and one that should be taken
seriously. The project would be strengthened by a "united front"
among all its parts. It would also make it easier for participants to
move from one area to another with little adjustment. All good things.

If Markdown is capable of everything that's currently being done with
Mallard and/or DocBook and/or [insert markup language here], then a
good cheat sheet with conversions from each/any of them to Markdown
would go a long way towards easing the learning curve and making the
adjustment gentle. I see that you linked to a cheat sheet, but a side
by side comparison would be even better.

I seem to remember that there are some seriously tricky things being
done in some of the docs (with the information presented being
dependent on the system viewing it, etc.), so it might be a good idea
to ask for examples of some of the trickier code so that it can be
attempted in Markdown before making the final decision.

Whether Markdown is easier to use or learn than the current tools is
a matter of opinion and will vary from person to person. I,
personally, prefer txt2tags over Markdown, but that could be because
I've used it for several years now and have all kinds of warm fuzzies
for its non-invasive markup (which doesn't affect word counts) and
pretty well unlimited extensibility. At the same time, I can
understand the viewpoint that a markup language that uses words is
more obvious to understand for a newcomer than something that uses
punctuation.

Either way, one of you mentioned that participation is currently at a
low, so it seems that now is a good time to make a change since there
are fewer people who would be affected by it (pleasantly or
otherwise).

My two cents.

-- 
Little Girl

There is no spoon.