Creating and maintaining API references

From PRPL
Jump to: navigation, search

References are the lowest level of a project's documentation. The purpose of references is to provide high quality explanations of appliation programming interfaces (APIs), functions and data structures.

Projects often make a few mistakes with references that are important to avoid. References should NOT be the only documentation on a project. Often times projects create autogenerated documentation, post it online and think they're done. This is not remotely sufficient for documentation and doesn't provide users with enough high-level information to understand the project.

Additionally, references should consist of more than autogenerated documentation. Autogenerated documentation is, at best, a starting point for creating references. References need to include more detail than a list of the functions and data structures, they should have enough information for users to understand what the functions and data structures do and how they fit together. Simple examples, with clear explanations of how to use the functionality.

How to write references[edit]

One way to understand references is they should be like the "dictionary" of your documentation while guides are like the "encyclopedia" of your documentation. Dictionaries include the description and basic usage of every possible word but they don't explain concepts. On the other hand, encyclopedias document concepts that combine various words into a larger whole. So References cover every data structure and function but they aren't designed to cover broad concepts. Broad concepts should be covered in guides which are like the "encyclopedia" of your documentation. The anal

References should cover all the data structures and functions consisting of the public API for a piece of code. The reference documentation for every data structure should include:

  • Data structure name
  • Names and types of every field (ideally with links to the reference for the type)
  • Description of how every field is used or potential uses. Think of this as justifying why the field is there: someone added this field to the type; why?
  • Description of how the data structure is used or potential uses. Similarly to fields, answer the question: why does this data structure exist? What is its purpose?

The reference documentation for functions follows quite similarly. Functions references should include:

  • Function name
  • Names and types of every parameter (ideally with links to the reference for the type)
  • Description of how the parameter is used or potential uses. Try to answer the question: why was this parameter created and how is it used in the function?
  • Description of what actually occurs inside the function and what's the function's intended purpose
  • Description of where and how the function is used. This description should include simple examples of usage.

The last bullet point is likely the trickiest. You don't want to fill the reference up with explanations about large concepts; that's really what guides are for. At the same time, you should provide necessary explanation using examples. If you find that you're starting to explain a broad concept, you should link to a guide related to that topic.

How to get started[edit]

When creating documentation, don't worry if your documentation isn't complete on the first try; that's normal. What's important is that you've created a document to work on together with the rest of the community.

Make sure to be honest in the documentation if you're unsure on something. It helps readers know that the shouldn't assume that a given part is totally correct. Additionally, it gives other community members a great place to start if they want to improve the documentation. Remember: it's okay to not know everything

Improving and maintaining references[edit]

References can take a substantial amount of work to maintain and improve. If you see something in the reference that could be clarified or improved, don't hesitate to do so. One particularly valuable activity is making sure references continue to be accurate when new versions are released. If there's been a change due to a new version, make sure to mention it in the summary of your changes. If you want get folks advice, either create a new Github issue or find an issue that relates to your topic (perhaps the one that documented the creation of the reference).

Creating new documentation[edit]

If you want to create new references, you should post your topic on the forum and summarize what it is you'd like to work on. One good example of doing is at http://forums.prplfoundation.org/t/procd-script-reference/40. The idea of this is that other folks might be also interested in your topic and want to help you out. After all, in almost all cases, the more the merrier! You certainly don't have to wait for folks to respond to start creating your documentation. Certain topics may require waiting but, in most cases, there's no harm in getting started right away.

To get started on new documentation, create a new page on the wiki by visiting http://wiki.prplfoundation.org. Go to the search box and type in the name of what you'd like your article to be and press Enter. It's usually easy to call it "topic reference," ex: 'procd script reference". Don't worry too much about the name, we can rename it later if necessary. The new empty page should come up and there will be a link saying "Create page" in the top right-hand tabs next to the search box. Click that and start editing your page! Make sure to post the URL of your brand new page to the forum post you created earlier. When you want to save your work, just add a summary and press "Save page".

As you complete more of the page, don't hesitate to update the forum topic with your progress. This allows others to help you out and give you advice while the page is being created. An example of how one might do this is at http://forums.prplfoundation.org/t/procd-script-reference/40

If you have any questions, don't hesitate to post to the prpl Foundation forums. Folks in the project want to help you participate in whatever way works best for you!