[Systers-dev] Developers Documentation

[Sarah Mei]

The most useful type of docs, for me, are those generated from the
source code. Any kind of file that needs to be separately updated is
doomed to be perpetually out of date.

Auto-generation on build is also useful because it's open - anyone can
generate the docs and put whatever interface they want on the
information. For example, the Rails documentation, as it is
conventionally generated, looks like this:
http://api.rubyonrails.org/

Not incredibly useful - just big lists of stuff. But someone else can
take it and make it ajax-ily searchable:
http://www.railsbrain.com/api/rails-2.3.2/doc/index.html

My $.02.

Sarah

On Thu, Jul 16, 2009 at 6:37 AM, Jennifer Redman<jenred at gmail.com> wrote:
> Anna Granudd - one of our fabulous GSoC students is soon going to begin
> working on updating and generally improving our Developer Documentation.
>  Now is a good time to let her know if there are any areas of the MM
> customizations that you found/find particularly difficult to understand from
> a development perspective.
> I've updated the wiki a little bit -- test plans for production roll-out are
> now there and some other odds and ends.
>
> For those of you not involved in the MM project, but have some suggestions
> about what makes good developer docs -- please send along your suggestions.
>  This can also include -- "I always need but can never find" type comments.
>  We are striving to be the best. Yeah Systers! (Sorry I'm up very early and
> get a little punchy) ;>.
>
> We should think of this as an opportunity to create a framework for
> documentation requirements for future projects as well.
>
> Thanks,
> Jen
>
>
> To unsubscribe from this conversation, send email to <systers-dev+documentation+unsubscribe at systers.org> or visit <http://systers.org/mailman/options/systers-dev?override=24&preference=0>
> To contribute to this conversation, use your mailer's reply-all or reply-group command or send your message to systers-dev+documentation at systers.org
> To start a new conversation, send email to <systers-dev+new at systers.org>
> To unsubscribe entirely from systers-dev, send email to <systers-dev-request at systers.org> with subject unsubscribe.
>