+- Wings 3D Development Forum (https://www.wings3d.com/forum)
+-- Forum: Wings 3D (https://www.wings3d.com/forum/forumdisplay.php?fid=1)
+--- Forum: Documentation Project (https://www.wings3d.com/forum/forumdisplay.php?fid=15)
+--- Thread: Documentation Strategy (/showthread.php?tid=43)
RE: Documentation Strategy - optigon - 11-25-2012
The best options I know of are:
- Install a wiki of our choice on wings3d.com and make it open to public registration
- Grant all those interested and trusted access to the wings website (wordpress)
- Use Wikibooks
But one of oort's comment made me think; is it better to have a single long page, or many linked pages with a table of contents?
RE: Documentation Strategy - puzzledpaul - 11-25-2012
(11-25-2012, 02:30 AM)optigon Wrote: But one of oort's comment made me think; is it better to have a single long page, or many linked pages with a table of contents?
My vote'd be for the latter option.
(different ppl could work on partic. subjects without affecting t'other pages ...and less chance of messing up the whole lot when adding / editing content)
pp
RE: Documentation Strategy - greytery - 11-25-2012
It comes down to the choice of tool: Wordpress vs Wiki.
When/if you reply to this - note the tool and syntax used is very much like a wiki, so it's not that bad - is it?
I would vote for the wiki approach, but that's from a user point of view; apart from familiarity with wikis, not much in it for me.
If you (note the 'you'
) set up a separate public wiki using, say, Mediawiki, then there's the additional admin and access management to consider. But perhaps you're thinking of Wordpress wiki plug-in. Advantages include: admin of single platform, same access control to content and same defence against spam bots etc. I think you'd still have to grant trusted access to the WP wiki.
The Wikibooks option advantages include: Its there. And wide open.
(But if the Wingswiki is set up, we must transfer and 'shutdown' the wikibooks stuff to point to new material.)
Single long page vs linked pages. ??
Isn't that like asking whether Erlang modules should be written as one long single module or written as , er, modules?
(Seriously though, why would you go for a single long page?)
RE: Documentation Strategy - optigon - 11-25-2012
I would go for the subject per page format as well, just notice that some wiki pages end up being super long.
Looking at wikibooks again, I have only part of it linked on the home page.
Here is the parent link:
http://en.wikibooks.org/wiki/Wings_3D
Looking at that link I am reminded of what I used to think of as blender spam. Does Further Reading about Wings3d really require reading about Blender?
A wiki is better than wordpress if we have the documentation open to be edited by the public. Wikis keep a history of all revisions, so if we get spammed, vandalised, or misinformation gets added, the page can be restored.
I like the idea of setting up our own wiki because then we can control the branding.
RE: Documentation Strategy - optigon - 11-25-2012
Wordpress does have past revisions available, but they are viewed in html.. so not very readable.
So if we go with a wiki, then the two contenders are Mediawiki and Dokuwiki.
RE: Documentation Strategy - greytery - 11-25-2012
Never heard of Dokuwiki before but it sounds the part; the clue is in the name. Seems a good fit.
Plus points claimed on the Dokuwiki website are ease of use and admin, better than Mediawiki. Plus the ACL list looks easier to manage. I see that they use Wikimedia's actual spam blacklists (sneaky, but why not?).
I noticed that 'Blender Spam' too. Perhaps that could work both ways
. But I can see why you lean towards a controlled approach to branding.
RE: Documentation Strategy - optigon - 11-25-2012
Not to jump the gun, but I just installed MediaWiki on the wings website.
http://www.wings3d.com/documentation/index.php/Main_Page
Dokuwiki intrigues me, but Mediawiki is probably more familiar to most.
No direct link from the main site yet and I haven't tested the registration either.
RE: Documentation Strategy - greytery - 02-16-2013
Hi,
I've been working on converting/updating the Old User manual to get it on to the Wings 3D site. Optigon - who should be VERY VERY BUSY elsewhere at the moment ;-) -has kindly let me in to the WordPress engine and I've started to upload some pages. Still a WIP - and a long ways to go!
At some point you may see things appearing - assuming I press the right buttons - and I'd appreciate comments and corrections. Either here or send me a private message.
I've previously tried editing material in the Dokuwiki but the response/performance was abysmal. I'm getting old, and don't have so much time to waste waiting for the next 503 error. So that's why I'm using WordPress.
gerytery
RE: Documentation Strategy - oort - 05-06-2013
greytery,
I was just looking around on Wings3D.com and noticed how much work you have done. Thanks! I will look more closely when I have time but the bits I glanced at looked great.
Thanks,
oort
RE: Documentation Strategy - greytery - 05-06-2013
Oort,
Thanks. I'm getting slower as a) the summer kicks in, and b) I realise how big a job this is!! The old manual and even your later updates don't cover the work that has been done with the plugins and other bits n'pieces that have gone into vsn 1.4.1. - let alone the changes happening in 1.5.
So there's a few gotchas along the way. But it's been a great journey along my personal learning curve. From a standing start, I even have strong opinions on Erlang now!- or Arlang as the Swedes say.
Earlier optigon was promised that I was set for finishing in February. I'm still on track - I didn't tell him WHICH February.
Any comments here or private appreciated.
greytery