How can we make things better? Documentation

bsoremsugar —  March 4, 2011 — 1 Comment

This biggest complaint I have heard from Sugar developers, both community and partner, is about our documentation. And with any software project, both open-source and closed-source, it is always a major struggling point.

We’ve taken an approach with the Developer’s Guide to create a cohesive manual that gives a large technical overview of the platform. This guide has been very helpful for many developers to learn how the platform works. That said, we’ve had lot’s of feedback about this handling our developer documentation in such a way, namely:

  • It’s very high level and not practical. The focus is about the concepts in the application but really doesn’t show very good examples of how you would actually do it.
  • It’s quite large and hard to grep ( so to speak ). Not as useful for a reference due to it’s length and high-level approach to the problem.
  • There’s missing an API reference for much of the classes in the application.
  • There’s nowhere where we list what has changed from a developer perspective in each release ( like new or changed functions, new upgrade-safe hooks, etc )

I think a big focus of our documentation is filling these voids, and making the documentation more approachable by everyone. While I’d love to have a larger conversation about this at SugarCon in April to get more community and partner input, I also want to get feedback now on the direction we should take and what other shortcomings we have with our documentation. Sound off in the comments or DM us on Twitter with your thoughts.

One response to How can we make things better? Documentation

  1. 
    Fabricio Longhi March 8, 2011 at 6:44 pm

    I think that your approach at documentation is not correct. There are a lot of things that can be done in Sugar, but no one knows about them (except for a few) because you don’t document them.
    How is it even possible that you don’t public a changelog?
    I believe that Sugar is very powerful for being open source, but if you don’t document or even communicate what can be done in a Sugar-way, the work for developers are going to get harder and frustrating…

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s