Better DokuWiki introduction text

DavidONE

2008-03-16, 23:55 #1

Member for 2 months · 6 posts
Group memberships: Members

Show profile ·

Link to this post

Subject: DokuWiki wiki update for locked pages

Hi all,

I have written a revised introduction for http://wiki.splitbrain.org/wiki:dokuwiki which I think better highlights the key features for new users. However, I've just noticed I cannot edit this page! I see that several wiki pages are locked - any reason for this? Spam? Vandalism?

Anyway, here is my change:

DokuWiki offers:

* a standards-compliant, simple-to-use [[wp>Wiki|wiki]] which allows users to create rich documentation repositories
* an environment for individuals, teams and companies to create and collaborate
* a simple yet powerful syntax which ensures data files remain readable outside the wiki and eases the creation of structured text
* unlimited page revisions allowing you to restore to any earlier page version
* data stored in plain text files – no database required
* [[plugins]] to extend and enhance the system
* much more! See the [[features]] for details

Please read the [[manual]] for a detailed explanation of how to use this powerful wiki system. For questions and contribtuions, please join [[http://forum.dokuwiki.org/|the forum]].

This post was edited 2 times, last on 2008-03-17, 01:14 by DavidONE.

andi (Administrator) 2008-03-17, 16:52 #2

Member since May 2006 · 654 posts · Location: Berlin Germany
Group memberships: Administrators, Members

Show profile ·

Link to this post

Quote by DavidONE:
I see that several wiki pages are locked - any reason for this? Spam? Vandalism?

exactly. the start page and the dokuwiki main page were frequently vandalized, but two should be the only protected ones IIRC.

Basically I like your suggested changes, but I'd like to have this description in a single paragraph without any bullets. This is because this first description is very often quoted in articles and listings via copy and paste. A bullet list like you suggest might be counterproductive in that case and is already available in the wiki:features page anyway.

Read this if you don't get any useful answers.

DavidONE

2008-03-17, 19:04 #3

Member for 2 months · 6 posts
Group memberships: Members

Show profile ·

Link to this post

OK, understand. http://wiki.splitbrain.org/wiki:syntax (which had a couple of parts I wanted to tidy a little) is locked and I thought there were others ... but, of course, I can't find them now.

I formatted with bullets because it makes it easier to scan for first-time visitors, but I appreciate your reasoning. I've 'paragraphed' it in to 3 - a single block would be too much IMHO, unless I chop out more words. See what you think:

DokuWiki is a standards-compliant, simple-to-use [[wp>Wiki|wiki]] which allows users to create rich documentation repositories . It provides an environment for individuals, teams and companies to create and collaborate using a simple yet powerful [[syntax]] that ensures data files remain structured and readable outside the wiki.

Unlimited page revisions allows restoration to any earlier page version, and with data stored in plain text files, no database is required. A powerful [[plugins|plugin]] architecture allows for extension and enhancement of the core system. See the [[features]] section for a full description of what DokuWiki has to offer.

The community-edited [[manual|DokuWiki manual]] will explain how to use this powerful wiki system. For questions and contributions, please join [[http://forum.dokuwiki.org/|the forum]].

If I can't get access to the syntax page, I'll maybe copy it out to my local install, edit it there and provide you with my suggested changes (hoping that no revisions are made before I hand it back).

DavidONE

2008-03-17, 19:10 #4

Member for 2 months · 6 posts
Group memberships: Members

Show profile ·

Link to this post

I've just noticed you're allowing edits from non-registered users and see some idiot has been vandalising the namespaces page today. Why not require registration for editing? It'll slow them down a bit....

andi (Administrator) 2008-03-18, 16:01 #5

Member since May 2006 · 654 posts · Location: Berlin Germany
Group memberships: Administrators, Members

Show profile ·

Link to this post

I updated the site with the suggested text. I'd like to get input by others - do you like this version better?

Note: I changed the subject line to match the discussion a bit better. Hope you don't mind.

Read this if you don't get any useful answers.

This post was edited on 2008-03-18, 18:53 by andi.

ChrisS 2008-03-18, 17:08 #6

Member since Sep 2006 · 82 posts
Group memberships: Members

Show profile ·

Link to this post

Not really. It seems to be marketing speak. I prefer the style of the text in the original, for me its clearer and more to the point.

The extra information on unlimited revisions and powerful plugin architecture is a worthwhile addition - as would be something that mentioned completely customisable templates.

DavidONE

2008-03-18, 18:31 #7

Member for 2 months · 6 posts
Group memberships: Members

Show profile ·

Link to this post

Chris,

Care to qualify that? Where's the 'marketing speak'?

There's no hyperbole, no superlatives, no clichéd phrases - just factual description AFAIC ... but, of course, I'm biased.

I've just noticed, however, that 'powerful' appears in each paragraph, which isn't great writing style. That should be changed.

ach 2008-03-18, 19:55 #8

Member since May 2006 · 99 posts
Group memberships: Members

Show profile ·

Link to this post

I do not like the first two sentences, but I like the rest of the new text better than the old.
It could be that I am of that opinion, because I am not a native speaker, though ...

"create rich documentation repositories" sounds too techy.

"It provides an environment for individuals, teams and companies to create and collaborate using a simple yet powerful syntax that ensures data files remain structured and readable outside the wiki.": All in all the sentence seems too long and complicated for an introduction (considering that could be the very first paragraph someone reads about DokuWiki who has no knowledge of wikis in general).

"environment" sounds techy.

Why list "individuals, teams and companies"? Couldn't just "users" be enough? The original "It is targeted at developer teams, workgroups and small companies." is better, because they are the actual "target groups".

"to create and collaborate": create what? Isn't there an object needed?

Sorry, I cannot really explain further why I do not like it ... It is just a feeling ...

ChrisS 2008-03-18, 21:01 #9

Member since Sep 2006 · 82 posts
Group memberships: Members

Show profile ·

Link to this post

ach has picked on the same parts that I didn't like. For me marketing speak is using long words which don't add much meaning, e.g. "rich documentation repositories" => "documentation". The sentences in the new version seem longer, where as the old version had shorter sentences which flowed together and answered the three key questions (what, who, why) one after the other.

After thinking about this earlier and again now, I really quite like the previous first paragraph. Although update that second sentence if the "who" has changed.

Keep the new second para (except remove the db stuff as that would be back in the first para) and possibly extend it to mention customisable templates (important if someone wants to "brand" their own wiki), rss feeds of edits (important to easily keep track of what's happening) and subscription to pages (important to an "owner" of a page). I can appreciate the need not to make the para too long ( :-)

) but I would rate those three things higher than plugins, plugins are mostly of interest to the technically minded looking to extend/integrate DW or once someone has become familiar enough with core DokuWiki to look to push it further using already published plugins.

And leave the new third para. :-D

andi (Administrator) 2008-03-18, 21:09 #10

Member since May 2006 · 654 posts · Location: Berlin Germany
Group memberships: Administrators, Members

Show profile ·

Link to this post

Chris could you rewrite the paragraphs as a whole, eg giving me something to copy'n'paste? ;-)

Read this if you don't get any useful answers.

DavidONE

2008-03-19, 07:02 #11

Member for 2 months · 6 posts
Group memberships: Members

Show profile ·

Link to this post

In reply to post #8

Quote by ach:
1... because I am not a native speaker, though ...

2... "create rich documentation repositories" sounds too techy.

3... too long and complicated for an introduction ...

4... Why list "individuals, teams and companies"? Couldn't just "users" be enough? The original "It is targeted at developer teams, workgroups and small companies." is better, because they are the actual "target groups".

5... "to create and collaborate": create what? Isn't there an object needed?

6... It is just a feeling ...

1. I find many non-native English speakers do a better job than those born with it

- but agreed, it needs to be readable without 90% reaching for their dictionary.

2. Who is the introduction for? I'm guessing it's going to be of interest to those who are technically competent / curious. End users (i.e. those who just add / edit content) will be more interested in the syntax page (which I feel needs to be re-worked, having recently read it as a new user)

3. I agree - which is why I used bullets initially, and would still choose that if I were king.

I think visitors to the site should take priority over those who copy and paste the introduction for use in reviews, etc. - but I understand andi's reasoning

4. Just "users" does not convey the ACL component, whereas "individuals, teams and companies" implies there is user / group access control. I changed the original because I see no difference between "developer teams" and "workgroups".

5. No, the previous sentence makes it clear we're talking about documentation.

6. Nothing wrong with that as an argument.

DavidONE

2008-03-19, 07:35 #12

Member for 2 months · 6 posts
Group memberships: Members

Show profile ·

Link to this post

In reply to post #9

Quote by ChrisS:
1... long words which don't add much meaning, e.g. "rich documentation repositories" => "documentation".

2... sentences in the new version seem longer, ... where as the old version had shorter sentences which flowed together and

3... answered the three key questions (what, who, why) one after the other.

4... I really quite like the previous first paragraph.

5... extend it to mention customisable templates ... rss feeds of edits ... subscription to pages

6... plugins are mostly of interest to the technically minded

7... leave the new third para.

1. Just 'documentation' suggests nothing to me - it could be a single page with plain text content. 'Rich' suggests formatting and structure. 'Repository' is an appropriate word here - http://dictionary.cambridge.org/define.a…?key=67032&d… - but maybe 'too much' for non-native (and some native!) English speakers?

2. Well, I was trying to convey more information and, as mentioned previously, I think this type of functionality list is best-suited to bullets

3. Good point. The original does that better.

4. There are problems with it. "mainly" is superfluous. "documentation of any kind" is not accurate (PDFs? Spreadsheets?). "makes sure" should be "ensures".

5. Good points.

6. Disagree. Think Firefox. If a system is extensible with plugins, it's much more useful than a monolithic application that relies solely on core development.

7. I'm pleased you liked something.

This post was edited on 2008-03-19, 07:44 by DavidONE.