Best practices in working with developers

From Outreach Wiki
Jump to: navigation, search

If you need to tell the developers that something is wrong, check out this guide to "reporting a bug". If you'd like to get something built, continue reading below!

Briefing developers[edit]

Developers need a combination of both the general thrust of what you are trying to do and specific details of what needs implementing.

In putting together a brief for a developer, try to include:

  • details of where data is stored (e.g. in a SQL database, via an API, in a spreadsheet)
  • the data formats that needs to be imported or exported (e.g. XML, JSON, HTML, Wikitext)
  • details of the exact operations that need to be undertaken on Wikipedia
  • what your expectations are: is it a quick-and-dirty hack or a sophisticated newbie-proof, reliable, tested piece of software.

In briefing a developer, try to include as much detail as possible on potential error conditions: what happens when the software doesn't function correctly? What happens if the data is broken in some way? You don't have to set these in stone, but it is important to think about how to handle these errors.

In the description of what you need, specify whether this is a one-off process or whether it will run continuously. The former can be safely hacked in ways the latter shouldn't be. The latter also means the developer is potentially taking on the responsibility of maintaining or supporting code indefinitely.

Key words to use[edit]

There are a number of key words you should try to use when describing the functionality you need...

  • for each, do: a lot of programming involves doing the same process to hundreds of different examples. Specify what the things are that need things to happen to, and what needs doing to them. Imagine you are asking a programmer to build essentially a production line for software. On that production line, raw information comes in and is manipulated and things get done either to that information or with that information. Specify what the information coming in is, and what you want done with it.
  • if, then, else: not all information that gets handled by the computer is to be handled the same.
  • in order, before, after: sometimes you care in what order things are done. If you tell me to program the computer to list the numbers between one and five inclusive and I printed out "5 2 4 1 3", are you satisfied?

Where to start the conversation[edit]

See mw:How to report a bug