Documentation

Vasher

I just wanted to take a moment and say how severely disappointed I am in the documentation in Achaea since I've returned. There have been a million features added which is great, but more often than not, they are documented only in the announce post when they were released, and not in the relevant help files. Some helpfiles are still more than 10 IRL years out of date. Classleads will fundamentally change a skill, but then the AB file for that skill is never updated, and the only source of that knowledge is some announce post that contains 50 classlead changes from 5 years ago. The way that artifacts works can be changed and never updated, some artifacts have a chance to instant true kill you, and this is mentioned nowhere. I even specifically tried to find this information now, and I cannot find reference to it anywhere.

There are many times that the only source of accurate information is people in the ACC clan, which means that basic information is kept behind impossible barriers if you don't know anyone in ACC there is no way to get this information.

The gold cap is a particularly heinous offender of this because there is no mention of it in a help file anywhere. When I found out it existed, I tried to find information on my own, even trying to search the announce posts having gone through this song and dance enough to know that is sometimes the only place things are mentioned, and while I can find mentions of it existing in posts of it being changed, I cannot find the original post about it because of the limits of using newssearch being a single word. Gold cap is not a single word, and Gold and Cap are so common that each yields hundreds of results.

Edit: I realized this post didn't have any positive suggestion of how to move forward. Newssearch being the only way to find some of this information is problematic because it only supports searching for a single word. The first step I think would be to address this try to expand newssearch to add different booleans and modifiers to try to reach the information you want to find.

I also think it would be wise to evaluate the development pipeline. Does it have a specific place where new documentation is meant to be added and why is that being missed so often?

Froggle

Good documentation takes a professional, specialized documentation team. Full stop. Developers are NOT tech writers. Project managers, game designers, and volunteer admins are NOT tech writers. Saying otherwise is probably going to make a tech writer's blood boil. Has any IRE project ever had the funds to support a professional documentation team with that singular focus? I've been following the MDN story closely and that's illuminating. https://twitter.com/__DavidFlanagan/status/1295220467813367808

Can class leads negotiate updates to AB scrolls? Can we use BUGs and ISSUEs for general HELP changes? Would IDEA work for new features that other players can support? These are tools we have right now so there are no new costs associated.

Crowd-sourcing documentation is interesting to me, but this is going to open up a lot of challenges with the risk of varying quality and favoritism between docs. What if wiki maintainer roles were handled like craft approvals, newbie guides, and mortal building? For help scrolls, the quality of a wiki could be satisfactory! Of course this idea would take hundreds of hours to implement, and then an ongoing volunteer cost of an admin monitoring the help file authors. No affordable solutions from me.

I strongly dislike using news posts for anything other than news. It is a poor substitute for a HELP/AB file for all the reasons already outlined. A fix to news searching, e.g. making it easier to search for 'gold cap', sounds awesome but orthogonal to the root issue of out-of-date documentation.

Saonji

Aetolia and Imperian literally both have a HELPEDIT command for players (which also awards points towards dailycredits, too). Think there's ABEDIT as well, I can't remember 100%.

It's surprising that Achaea doesn't have it. The only real downside is that with how many players there are, it may end up chewing into admin time quite a bit. Could always have it so only leaders can use the command.