Documentation - wiki?

a773 2016-10-05 07:42:47 UTC #1

So I found the correct way of adding objects to the contrib library. Wouldn't it be an idea with a wiki where I could add this for-me-new-found-info so the next guy can easily find it? Obviously most things ATM works like this: play around with axoloti, if the user get's in trouble, search the forum, if you can't find it, ask. But a more structured "manual" would be great.

Huge task, I know, but for starters a wiki with fragments would be great. As more info is added, we could start grouping it and build the wiki to the point where it's a more-or-less complete manual.

thetechnobear 2016-10-05 08:42:04 UTC #2

we use discourse for this, which allows wiki posts (post that anyone can edit)

so you can create topics you would like for the 'user guide', and place directly in:

http://community.axoloti.com/c/user-guide

(if not, the I can move them there)
THEN, I can change their type to 'wiki' posts, so that any users can edit.

(you can also edit existing ones, so feel free to do this... again if you dont have permissions let me know)

there is virtually no difference to this and using wiki, with the added bonus that its all in one place, and users searching on the forum will find 'user guide topics too. .. and of course discourse has many functions, including tags etc.

currently, Ive seen no evidence that it the 'technology' (using discourse) thats preventing users contributing to the manual... it just seems that the community has little desire to actually contribute content.
( so personally, I'm not willing to change tech, as i don't believe it will solve the underlying issue - of course others are at liberty to create a wiki if they so desire)

thetechnobear 2016-10-05 08:52:52 UTC #3

btw:
When i created the community library, I also created a set of videos which showed how use it (including how to add objects to the community library.)
these were linked to in the main contributor library topic
http://community.axoloti.com/t/about-the-community-library-category/1005
(see the bottom part)

They are a bit dated , but think much is still relevant.

It would be a good user guide topic, so feel free to contribute

a773 2016-10-06 09:25:31 UTC #4

Ok, I didn't know that was the intention, I'll give it a try.

I still feel like it's quite scattered, and that a real wiki would be useful. It would make it possible to structure the information either in a much more linear way (aka book/manual), or have users add bits outside the structure, and other users could fit them in.

I realize the videos were created with the best intentions in mind, and probably was quite time consuming. I personally much prefer written text, easier for follow in my own pace, scan to find the relevant info and most importantly are searchable.

thetechnobear 2016-10-06 15:42:22 UTC #5

As i said, if others want to do something like this, they are very welcome.

a773 2016-10-06 15:44:17 UTC #6

You mean start a wiki?

thetechnobear 2016-10-06 16:54:17 UTC #7

yes, but this is only my opinion - and its @johannes that would decide.

but I repeat, I don't think the problem is technology (wiki vs discourse vs a.n.other)
no one has said to us, they are not writing content because they don't like discourse. (except perhaps you are in this thread )

personally, when I wrote the user guide pages, I was happy enough with discourse, its not perfect, but it also didn't prevent me doing anything I needed.

and in my opinion there is absolutely no point in switching technology (better or not) unless this means others will contribute more documentation, which I cannot see really.

but its a thorny question, Ive really no idea how to encourage the community to get involved in the documentation process. I guess, documentation is just not much fun, its more fun patching and creating objects

EDIT: Ive moved this to the website/forum section, and this seems more appropriate.

johannes 2016-10-06 16:56:50 UTC #8

I believe the "discourse" forum software has enough wiki-like facilities, that I see little reason to setup a dedicated wiki on the axoloti server. It's all there, MarkDown formatting, versioning. The only thing that does not work well is concurrent edits by multiple users (they can get lost).

For instance this post can be edited once you reach "basic trust level" here, you already have reached that.

a773 2016-10-07 11:39:04 UTC #9

I tried to edit "installing on linux" (first post), was promted to select a category, and couldn't select "user guide". What to do?

johannes 2016-10-07 12:02:52 UTC #10

Perhaps you tried to edit the post subject, rather than the post message?

Use the pencil button highlighted in yellow.

a773 2016-10-07 12:47:58 UTC #11

I see no yellow, but clicking the right-most pencil brings up edit, where I'm prompted to select category before I can save. I cannot select "user guide" (it's not on the list), I imagine that selecting one of the available categories will mess things up...

johannes 2016-10-07 12:51:56 UTC #12

I painted the yellow highlight on the screenshot.
I'm checking the forum settings now...

a773 2016-10-07 12:53:19 UTC #13

Ok, was looking for yellow...

a773 2016-10-07 12:54:49 UTC #14

Quick guess: wiki post are only editable by moderators, johannes + the technobear are both moderators, I'm not...

johannes 2016-10-07 13:12:59 UTC #15

Sorry for my misinformation, could you try the green edit button, painted in yellow on the screenshot below

a773 2016-10-07 13:48:15 UTC #16

Yeah, sorry for the confusion as well. I did in fact press the green pencil (the right-most pencil brings up the history, without the possibility to edit).

So problem remains: after editing with the green (left-most) pencil, I'm prompted to select category, and "user guide" is not on the list...

a773 2016-10-07 14:22:21 UTC #17

NB: I'm not allowed to post a new topic in the "user guide" category either...

a773 2016-10-07 14:25:51 UTC #18

Not sure if @johannes did something, but this just happened, and it helped a lot, now I seem to be able to edit wiki posts:

johannes 2016-10-07 14:37:24 UTC #19

Yes, I have indeed manually granted you "Trust Level 2", and that is the required trust level for editing wiki topics.
Normally this happens automatically if you're active for a while here. Currently 111 users have reached "Trust Level 2" automatically. In a way it is good to have some shielding from spam bots. So far this forum has been nearly completely free of spambots, and I 'd like to keep it that way, so I'm hesitant to change the forum settings.
But if anyone wants trust level 2 for a reason, sent me a PM...