Thinking of reorganising my documentation wiki

For AI and campaign script related discussions and questions

Thinking of reorganising my documentation wiki

Postby aubergine » 17 Jan 2013, 22:34

Currently the wiki where I keep an alternate version of the JS API docs is set-up like this:

Code: Select all
* API
     * Constants
     * Environment (as in JS API environment)
     * Events
     * Functions
     * Globals
     * Objects


As the JS API continues to grow, it's getting harder to find stuff -- in particular the functions section was turning in to a huge list of functions.

The wiki has a very good search engine built-in, so if you know the name of a function/global/event/whatever you can just type it in to the search box and it will show suggested page links. With that in mind...

I'm trying an experiment, currently limited to functions (and I'm still in the process of moving stuff around as I type this), whereby I'm grouping them by what they relate to.

For example: Droids, Structures, Features, etc...

This will help group related functions together, and each 'topic' will have a summary page that also contains references to other things (eg. the Map topic will have links to FlaME, etc).

To do this, I'm moving the various "Quick Reference" pages I had in to the Functions section, then making related functions children of those pages as applicable.

This should make it easier to find stuff when you don't know what you're looking for. For example, if you want to do something with droids, but can't remember the function name, just look in the Droids topic.

I'm also thinking of doing the same with constants and objects, and then making the various topics top-level pages that appear in the sidebar. So you could click "Droids" and see all functions, constants and objects relating to droids.

Obviously, some things won't fit neatly in to this scheme. For example, eventDestroyed relates to features, droids and structures. I'm not quite sure how to deal with that yet, I might have to make stub pages or something. In fact, I might put events in their own section, and then have redirect pages within Droids, Structures, etc., topics?

Just wanted to know if anyone has feedback before I get too far in to making these changes.... In particular, when you go looking for a constant, for example, will it seem more natural to look under Droids for that constant, or would you expect to go look in a constants section instead?
"Dedicated to discovering Warzone artefacts, and sharing them freely for the benefit of the community."
-- https://warzone.atlassian.net/wiki/display/GO
User avatar
aubergine
Professional
Professional
 
Posts: 3459
Joined: 10 Oct 2010, 00:58

Re: Thinking of reorganising my documentation wiki

Postby aubergine » 17 Jan 2013, 23:05

In fact, I'm even considering merging the JS API wiki in to the main modding guide.

The result would be that when you clock on the Map topic, for example, you'll not only see all JS API features relating to the map, but also all other map-related modding stuff, such as links to map editing (FlaME, etc).

Is that too big a change? Assuming the JS API stuff was clearly identified in each topic, and bearing in mind the auto-suggest search box, do you think all the other stuff would get in the way?
"Dedicated to discovering Warzone artefacts, and sharing them freely for the benefit of the community."
-- https://warzone.atlassian.net/wiki/display/GO
User avatar
aubergine
Professional
Professional
 
Posts: 3459
Joined: 10 Oct 2010, 00:58

Re: Thinking of reorganising my documentation wiki

Postby aubergine » 18 Jan 2013, 01:20

I've decided not to merge the JS wiki with the modding wiki. One of the benefits of having JS wiki separated out is browseability, to find stuff you don't even know exists. It's much easier for me to create automated lists of just JS API stuff if all the JS API stuff is in it's own wiki space.

I do, however, want to make the navigation more consistent between JS wiki and modding wiki, using the same section names for the same things.

Also, I'm getting a strange sense of deja vu -- I'm sure I tried reorganising the wiki in the past but aborted the task. This time it seems to be going much better (I guess because the JS API is now much bigger and it's easier to see logical groupings for things).
"Dedicated to discovering Warzone artefacts, and sharing them freely for the benefit of the community."
-- https://warzone.atlassian.net/wiki/display/GO
User avatar
aubergine
Professional
Professional
 
Posts: 3459
Joined: 10 Oct 2010, 00:58

Re: Thinking of reorganising my documentation wiki

Postby Goth Zagog-Thou » 18 Jan 2013, 02:16

I dunno, the current one seems to work fine for my needs. Only thing I'd suggest is expanding the 'Related Functions" section. :)
User avatar
Goth Zagog-Thou
Regular
Regular
 
Posts: 1582
Joined: 06 Jan 2007, 08:08
Location: Delta Base

Re: Thinking of reorganising my documentation wiki

Postby aubergine » 18 Jan 2013, 02:25

WIll do - one of the problems I was having with "see also" lists is keeping them up to date. Eg. if a new feature for droids gets added, there's a gazillion pages that need updating.

However, with the new structure, I can just include a list of pages in the topic. I might actually create some hidden pages with lists of the links, and then I can include those in the sidebar = related functions lists are centrally maintained & more consistent. Yes, that sounds like plan! *Goes off to mass-edit the sidebars....* I may be quiet for a while...
"Dedicated to discovering Warzone artefacts, and sharing them freely for the benefit of the community."
-- https://warzone.atlassian.net/wiki/display/GO
User avatar
aubergine
Professional
Professional
 
Posts: 3459
Joined: 10 Oct 2010, 00:58

Re: Thinking of reorganising my documentation wiki

Postby Goth Zagog-Thou » 18 Jan 2013, 02:30

Gotta love tags. :P
User avatar
Goth Zagog-Thou
Regular
Regular
 
Posts: 1582
Joined: 06 Jan 2007, 08:08
Location: Delta Base

Re: Thinking of reorganising my documentation wiki

Postby Goth Zagog-Thou » 21 Jan 2013, 14:07

Looks like you're doing a fine job, Aubergine. Keep up the great work! :D
User avatar
Goth Zagog-Thou
Regular
Regular
 
Posts: 1582
Joined: 06 Jan 2007, 08:08
Location: Delta Base


Return to Scripting