EVE Technology Lab

Documentation for third party-devs is still lacking. Bad. I had hoped with the developer site I would get time to improve it, but lack of time and my horrible writing skills has prevented that. So I have been trying to brainstorm ways to make it better, preferably involving the community some how.

I would love any suggestions you guys have. One idea that was raised was putting the docs on GitHub and use ReadTheDocs to generate fancy looking stuff. Could also go the route of just using Sphinx from those to generate the docs and host on the developers site. This has the nice advantage of anyone being able to contribute like a Wiki, but because integrates have to come through pull requests it's still vetted by a dev and can be linked to from the developers site. But maybe that's a higher barrier of entry than going back to Wiki pages... I dunno.

Looking for suggestions.

I've had some success recently using MkDocs, it's a lot like sphinx but lets you use Markdown rather than ReStructuredText, so the barrier to entry is a bit lower. It generates your standard nice readthedocs style documentation.

My ISK 0.02...

It goes without saying that CCP dev time is a precious resource. I'd rather see you spend most of your time doing things only CCP devs can do, and let the community do the rest. To that end:

Things only CCP devs can do:

1. Generate the definitive list of available API calls, the types of their expected arguments, and the types of their results.
2. Provide definitive answers on what the calls do (i.e. explain semantics).
3. (Maybe) provide test data for various API calls.

Things the community can do:

1. Write all this stuff down.
2. Figure out where the holes are, ask for more clarification, etc.
3. Generate reference clients, unit tests, etc.

I would vote to focus on auto-generating documentation which lists the complete API, and export it in a wiki-able format. Pick your favorite markup for code based APIs. For the SDE, the community could probably help here as the SDE is exported and there are numerous auto-doc tools for SQL.

Once the definitive API is exported, I'd ask the community to work on filling in the documentation, and I'd ask CCP to make themselves available to answer questions in some systematic way. I think you need to ask some members of the community to serve as stewards here, e.g. prioritize the questions that need answering. Then ideally you'd make yourself available to this group on a regular basis, e.g. pick 1 day a month to plow through the next N API documentation questions. Using NED as a starting point, a good chunk of the docs can already be filled in by the community. Devs from the EVEMons and zKillboards of the world would probably be great stewards here.

One last bit: having some place to collect API sample outputs would be extremely valuable. I think the community could shepherd this as well if there was a definitive place to put it. CCP may need to help for things that not all players have access to, like what the result of an Outpost API call looks like.

Note: this would be a great topic to discuss over brews or in a breakout session at fanfest. Just a thought...

I agree with salacious necrosis. While the documentation is an integral part of 3rd party applications, the devs have much more pressing matters to attend to such as expanding CREST or improving the game.

Unfortunately, I can't make it to fanfest this year due to my work schedule but I would love for there to be an interactive session on twitch during fanfest or maybe some sort of real-time discussion between players who are interested in 3rd party documentation and development (probably two due to the time shifts) with or without a dev just so we as a community can prioritize and standardize the documentation process. The entire thing would be recorded for review by the devs or by other players who couldn't make it.

If I can do something to help, please let me know.

We totally agree with the lack of documentation provided for third parties. With our Community Development Program (CDP) we have completed several community projects with more pending. We see a lot of the same questions, issues and problems.

We are almost done creating our public and primary System for the Academy of Evil, (we killing important bugs atm). Within one of the modules we have created a system similar to a Wiki that meets the power of Wordpress for the purposes a new way of displaying EVE Online related Information only. The 6 months for the module will hopefully pay off.

Planned for the system is to display, summarize, and organize EVE Online Game Items, Mechanics and General Data while making it update*able from the entire community in a unique way while ensuring the information and data is correct as much as possible.

It will be simple to add a Developers Area to the system via a plugin. We would however, need the community to help gather and post data from developers.

I think something On Github and using markdown might do a lot at least for most current third party developers since most of us already use it or have for other stuff we do. It also, if setup right, allows people to have local copies to look at when offline etc which can be useful at times. This would also allow everyone to use the issue system so anything that isn't clear from what the CCP developers write people can ask about it or even make feature request for thing they'd like to see better documented and as the community writes stuff they can do pull request etc as well and you just merge it when you feel it's ready and you have time.

All this can be done of course in a wiki but like someone else said that hasn't worked very well so far. I think one of the reason the current wiki stuff hasn't worked well is it more hidden vs something on github where it's highly visible at least to most developers. You could even just use the built-in wiki on github since it's just a branch in the project and people can add comments to the page as well. An added advantage is Gibhub also let's you use RST or several other markup systems and everyone can simply use what they like and it'll take care of the conversion for you. Use the code part of the project for where people can share their example code from the wiki pages etc. or for thing like tutorials can use a mix of code files and markdown files with the code. Basically it give a lot more flexibly for people to contribute to everything vs having something that more fixed if done other places. If you do it as an organization you can even have several projects in it say for different programming languages or XML vs CREST etc then have a master project that begins them all together. You could probably if you want from there also pull it into the existing wikis at CCP.

It also let's you do as someone else suggested to have something like the ISD manage some of the day to day stuff where they can do a lot of the basic merging etc but still leave just CCP employees as owners. You can also setup group for letting people do edit on only part of things etc as well. Anyway thats some of my idea on it

If CCP devs are incapable of producing a coherent product, simply open source the lot, MD files and API functionality, and let pull requests sort out the women from the boys.

After a night of sleep, here's my suggestion to overcome the problem of producing a "clean" (=complete, correct/error free and approved) starting point (because that's a lot of effort in the current state) and continue from there with the help/additions of the community. Be warned, though: this involves spending a bit of money.

- Book a technical writer for the task
- Have him pull together the information spread all over the various sources into one "document"
- Sign off the initial relaese
- Let the community start to commit to this

There are a lot of tools which allow approved publication. All have their pros and cons and it's somewhat a matter of taste which one to use. My personal stance on this is that I rather use a less-liked piece of software, but with a decent "starting point" than a tool with all the bells and whistles that I can dream of, but non-existant content.

I feel your pain, I have horrible writing skills as well.

Preferably CCP would hire someone to maintain this documentation, someone who would be working on it full time until it is finished, and then as much time as necessary to keep it updated. You would provide that person with any information they request, and they turn it into presentable consumable documentation. Maybe even after that the art department (or some graphically adept resource) puts another layer of polish to give it that professional look. If CCP wants to be excellent, they will do something like this.

Being that may not happen as soon as we would like, why not bribe the community with some in-game bling. Something from ship skins to maybe even plex. Maybe some other cool perk that no one objects to. Or maybe out of game bling like ship models. You already know MMO players eat that **** up, and should boost participation.

Perhaps discussion threads attached to the wiki pages that anyone can contribute to. On the original topic page mention to use the discussion to assist in improving the documentation. People might contribute original content, or maybe they propose a new format, layout, or re-writes. Whatever is deemed valuable enough to include on the main topic page, you copy and paste.

This should not be a big project. It doesn't need a wiki, or any staff or volunteers to manage it.

It is not a big API. The methods could be defined in a short PDF document. Then package working examples that can be run in a development environment.

Two weeks work for three code monkeys, is massive overkill.