These forums have been archived and are now read-only.

The new forums are live and can be found at https://forums.eveonline.com/

EVE Technology Lab

 
  • Topic is locked indefinitely.
12Next page
 

Third-party documentation discussion

First post
Author
CCP FoxFour
C C P
C C P Alliance
#1 - 2015-02-10 10:47:00 UTC
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.

@CCP_FoxFour // Technical Designer // Team Tech Co

Third-party developer? Check out the official developers site for dev blogs, resources, and more.

Aineko Macx
#2 - 2015-02-10 11:06:20 UTC
Sounds like you want to offload the writing of documentation to the community. That's not encouraging. But if that is the route we'll take I'd like to see the neweden-dev Wiki to receive the communities writing output. Maybe with some devs having editor rights there (not sure if this isn't the case already).
Lucia Denniard
Half Empty
skill urself
#3 - 2015-02-10 11:08:35 UTC
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.
CCP FoxFour
C C P
C C P Alliance
#4 - 2015-02-10 11:12:24 UTC
Aineko Macx wrote:
Sounds like you want to offload the writing of documentation to the community. That's not encouraging. But if that is the route we'll take I'd like to see the neweden-dev Wiki to receive the communities writing output. Maybe with some devs having editor rights there (not sure if this isn't the case already).


I am looking for assistance, not to offload it all. I am also still slowly working on the auto generated documentation for information on individual CREST resources.

@CCP_FoxFour // Technical Designer // Team Tech Co

Third-party developer? Check out the official developers site for dev blogs, resources, and more.

salacious necrosis
Garoun Investment Bank
Gallente Federation
#5 - 2015-02-10 13:07:55 UTC
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...

Use EveKit ! - Tools for EVE Online 3rd party development

CCP FoxFour
C C P
C C P Alliance
#6 - 2015-02-10 13:37:05 UTC
salacious necrosis wrote:
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...



Thank you very much for the thoughtful answer. Gives me some good ideas. :) Also, yes, much discussion during FanFest.

@CCP_FoxFour // Technical Designer // Team Tech Co

Third-party developer? Check out the official developers site for dev blogs, resources, and more.

Makari Aeron
Winnie Blues and VB Crew
Tactical Supremacy
#7 - 2015-02-10 14:29:09 UTC  |  Edited by: Makari Aeron
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.

CCP RedDawn: Ugly people are just playing life on HARD mode. Personally, I'm playing on an INFERNO difficulty.

CCP Goliath: I often believe that the best way to get something done is to shout at the person trying to help you. http://goo.gl/PKGDP

Ortho Loess
Knight Odds
Curatores Veritatis Alliance
#8 - 2015-02-10 15:02:13 UTC
While I'd ideally like to see CCP allocate more dev-time to documentation, I'm also happy to help out as part of the community. There is a lot of useful info scattered through this forum section, as well as on the dev site. There's also (at least) 2 major third-party sites with a mix of very good, and badly out of date or incomplete information.

I like the sphinx idea (or mkdocs - having used neither, I'm in no position to choose). With the source on github. (Docs hosted on dev site)

The history of EVE and official wikis is not great...

I also think that having some community editors would be a good idea (could even string it on to the ISD program...).
Possible additions to this:

  • Have a special forum section, for just the community editors and devs who might actually be interested in answering questions.
  • Give the community editors rights on the github docs repo.
  • Seek permission from anyone hosting significant amounts of 3rd-party documentation to copy it.
  • Have CCP management allocate dev time to answering questions from the community editors in a timely manner
  • Possibly offer some kind of rewards to hard-working community devs - e.g. in game items, like clothing or isk


Getting the whole project off the ground is going to require more time that you are currently able to allocate to docs, however much help you get from the community. Just putting up an empty wiki and saying go for it, would be quick and easy, but I don't think it would end up being useful.

As for Fanfest: a lot of us will be there and eager to discuss. could you fit an extra round-table (if that's the right term) into the program? Keep it fairly quiet (no need to put it in the program that gets sent out), the topic of "developer tools documentation" should keep away anyone who's not interested in helping out. Maybe a productive discussion can happen.
Darius Pythe
Academy of EVE
Evil At Work
#9 - 2015-02-10 19:36:31 UTC
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.

Member of the Evil At Work Network.

Ortho Loess
Knight Odds
Curatores Veritatis Alliance
#10 - 2015-02-10 20:31:04 UTC
Sounds like a great project you have going. As someone who has been googling all sorts of obscure stuff since 2007, I definitely look forward to having a reliable source for all the various game data.

As for the dev documentation, I think it would be better to have it hosted by CCP and under their control. I do have reservations on this, as if FoxFour ever gets moved off of this, we're unlikely to get someone anywhere near as commited to actually being helpful to 3rd party devs.

I still want to give CCP the benefit of the doubt here, and the chance to host a really good set of docs. I do think that strong community involvement is important though, at a level beyond just making suggestions for changes.
Dragonaire
Here there be Dragons
#11 - 2015-02-11 05:00:31 UTC
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 Blink

Finds camping stations from the inside much easier. Designer of Yapeal for the Eve API. Check out the Yapeal PHP API Library thread.

Hel O'Ween
Men On A Mission
#12 - 2015-02-12 11:15:45 UTC
The challenge at hand as I see it is:

- Let CCP "own" the project and approve official releases
- Let the community help out with "content"
- Get out "official" content in a timely manner

This all boils down to a very EVE'ish problem: Trust!

The community needs to trust CCP that content provided by them is published in a timely manner. CCP needs to trust the community with the content, in order to publish timely.

I'm not sure how to solve this dilemma. Since the invention of the EVElopedia, we basically had the tools for doing the above. EVElopedia was the "official" source, but lacking in (up-to-date)content. wiki.eve-id.net had the content, but was lacking the official approval.

And since that time, the conflict (of trust) hasn't been resolved. I think this needs to be solved first, before talking/discussing about what tools to use. And to be quite honest: I have no idea how to do that. What?

EVEWalletAware - an offline wallet manager.

SJ Astralana
Syncore
#13 - 2015-02-12 12:13:20 UTC
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.

Hyperdrive your production business: Eve Production Manager

Ortho Loess
Knight Odds
Curatores Veritatis Alliance
#14 - 2015-02-12 13:47:40 UTC
Hel O'Ween wrote:
The challenge at hand as I see it is:

- Let CCP "own" the project and approve official releases
- Let the community help out with "content"
- Get out "official" content in a timely manner

This all boils down to a very EVE'ish problem: Trust!

The community needs to trust CCP that content provided by them is published in a timely manner. CCP needs to trust the community with the content, in order to publish timely.

I'm not sure how to solve this dilemma. Since the invention of the EVElopedia, we basically had the tools for doing the above. EVElopedia was the "official" source, but lacking in (up-to-date)content. wiki.eve-id.net had the content, but was lacking the official approval.

And since that time, the conflict (of trust) hasn't been resolved. I think this needs to be solved first, before talking/discussing about what tools to use. And to be quite honest: I have no idea how to do that. What?


One of the great things about github is that things get approved before inclusion, so there can be checking of information.

One of the worst things about github is that things need to be approved before inclusion. If this is left just to FoxFour, he simply won't have enough time to keep on track of it.

Cue the community editors. All are known to CCP, the github account that is given edit rights on the repo is tied to a particular EVE account, malicious editing suddenly has potential consequences.

Anyone can write a new bit of documentation and submit a pull request, or if they see an issue, but don't know how to fix it, submit an issue. The editors can just approve the obvious ones, or make simple fixed for issues. Test out more complex stuff themselves. Where there is something they can't test or fix themselves, they escalate it to the dev team.

Of course, this style of approach could potentially work with other systems running it instead or github, but I like the open-ness, the issue tracker, the collaboration tools.

Final suggestion: think carefully about what kind of license the docs will be published under. My recommendation is Creative Commons (perhaps with the exception of certain code excerpts). You can't go fr the kind of restrictions that tend to find their way into CCP agreements, or it wouldn't be allowed on github. Always start at as permissive as possible and only close off rights where there is a solid need to do so.
Hel O'Ween
Men On A Mission
#15 - 2015-02-13 08:30:13 UTC
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.

EVEWalletAware - an offline wallet manager.

Shawn Gallentino
Heaven's Harvesters
#16 - 2015-02-14 00:44:46 UTC
This seems to be a case of trust. Ultimately, do you trust the community to do a good job at writing the documentation? For example, do you trust the users of Wikipedia to write those wiki entries we're so fond of. The journey of a thousand pages of documentation starts with the table of contents. Do the T.O.C, publish that and see where we go from there.
Locupleto
Lead Venture
#17 - 2015-02-15 20:53:38 UTC
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.
Pestilen Ratte
The Scope
Gallente Federation
#18 - 2015-02-16 11:19:02 UTC
It is no easy task to write good API documentation. You have no control over your reader's comprehension, and folks who read code documentation have massively variable comprehension of code itself. Put simply, the only way you can really please everyone is to teach programming in the language from scratch. Otherwise, those can only half sort of code will cry out "I still don't get it!", and they will be right.

You don't want to teach programming from scratch. So...

Apple handle this challenge in a neat way. They are not the smallest company around, so maybe check their API documentation out.

They have very sparse API summaries with methods statements set out as definitions only. It is up to the reader to know how to implement methods in the language.

Then, they supply examples of the code in action, doing very basic stuff. So with one small example program, they might include 20 or 30 methods. It doesn't take too many example programs to cover the whole API.

They do not try to be exhaustive. Just the plain vanilla method definitions and links to examples in action. They leave into the reader to use it in novel ways and integrate the methods into their overall app.

Frankly, if you can't understand a method from the definition and the example, you need to go back and learn how to code.

CCP is playing well with plain vanilla definitions and example code.

Pestilen Ratte
The Scope
Gallente Federation
#19 - 2015-02-16 11:22:55 UTC  |  Edited by: Pestilen Ratte
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.
Ortho Loess
Knight Odds
Curatores Veritatis Alliance
#20 - 2015-02-16 18:30:28 UTC
I got a bit bored and decided to have a go at an outline for the structure of developer documentation.

There's definitely stuff missing, and almost certainly some stupid choices I've made on where to put stuff, and how to divide it up.

There is definitely a need for as many examples as possible, using as many different languages as possible, but I'm not sure if they should go under each main area, or have one big collection just for code examples. I think either way, the large-block examples should supplement inline examples in the main body of the guides.

Introduction
    How to contribute
SSO
    Authentication flow
        Obtaining character details
    Refresh Tokens
    SSO for browser apps (Implicit flow)
    considerations for non-browser applications
CREST
    Endpoints
    Authentication and Scopes
    Walking through endpoints
    Rate limits, errors and user-agent
    Versioning and Accept Headers
    Examples
XML API
    API keys and access masks
        Create predefined
    Endpoints
    Cache styles
SDE
    What's included
    Table reference
    Conversions
    Tips on use
Image Server
    Image Export Collection
Frameworks
    PHP
    .NET
    JS
Quick Reference
    Root URLs
12Next page