A dedicated place for Haxe docs + new format

[Marcelo de Moraes Serpa]

As an idea to address the problem of documentation that haunts Haxe as of now - since I think Haxe deserves its own website for docs - I'd say we need a website/format like this one: http://railsapi.com/

I don't think the wiki format scales very well, at least that's my experience. It could of course, be used for articles, but any material that needs to be kept up to date and easily searchable, such as the API, should use a format like the one on railsapi.com.

Other sites that document Ruby and related libs:

http://ruby-doc.org/

http://apidock.com/

I'm not sure if Haxe generates the API docs from source-code, does it? If so, we can adapt that to generate a couple of HTML files and then add the necessary ajax boilerplate. Keep it as automated as possible, so that it's easy to keep it up to date.

I'd be willing to help with this project, if we can agree on a format, workflow and domain name :)

- Marcelo

[Tarwin Stroh-Spijer]

I don't agree that a different domain is such a great idea though ...


Tarwin Stroh-Spijer
_______________________

Touch My Pixel
http://www.touchmypixel.com/
cell: +1 650 842 0920
_______________________

- Marcelo

--
To post to this group haxe...@googlegroups.com
http://groups.google.com/group/haxelang?hl=en

[Marcelo de Moraes Serpa]

It could be docs.haxe.org or api.haxe.org.

- Marcelo

[Marcelo de Moraes Serpa]

Anyway, the point is not the domain/path, but the format. The current one is hard to reach and search, doesn't provide a good user experience IMHO.

- Marcelo

[Raoul Duke]

On Thu, May 24, 2012 at 11:28 AM, Marcelo de Moraes Serpa
<fullofc...@gmail.com> wrote:
> Anyway, the point is not the domain/path, but the format. The current one is
> hard to reach and search, doesn't provide a good user experience IMHO.

yeah.

i would like there to still be a wiki. it would be good if there were
wiki software that automatically sorted the search results so that
older pages would get pushed down in the results...

[Marcelo de Moraes Serpa]

The problem with the current wiki is that it's hard to edit. And before someone says it's not, try a simpler wiki based on GIT, for example. Plain text files, distributed, locally available and easy to update and check the history using simpler tools. I'm sure many will agree with me, other might not.

But the point is the user experience of the wiki. The GUI is awkward, and hard to search, compared to the other sites I've listed (try them out).

And of course, I'd like to know how the API is generated. Ideally it should come from the Haxe source itself, and an export tool should be used to transform it to a web GUI that provides a nice UX.

Lastly, the current "Documentation" section is a simple, confusing list. Can't seem to make sense of the structure. I can't even find "Macros" in there (I wanted to read about it). Its structure should be rethought.

Please see this a constructive criticism, and I'm willing to help, as I currently mainly do web development.

- Marcelo

[Raoul Duke]

hi,

> Please see this a constructive criticism, and I'm willing to help, as I
> currently mainly do web development.

i am with you 101% on the frustrations with the documentation. it is
not good to ever say e.g. "oh it is all there (somewhere) in the docs"
and then to have the docs be so unhelpfully unusable. if there are
tools that make the docs better, i think that will be a great help.

[David Holaň]

I don't get one thing. Page about class is generated from comments in its source code, right? But at the same time it's still a wiki page so anybody can change it. What happens when source code gets updated? The wiki and comments should be kept in sync, shouldn't they?

Oh and the "Available in ..." notes are indistinguishable from links. Links don't look much like links.

2012/5/24 Raoul Duke <rao...@gmail.com>

[Raoul Duke]

hi,

On Thu, May 24, 2012 at 11:52 AM, David Holaň
<paladin....@gmail.com> wrote:
> I don't get one thing. Page about class is generated from comments in its
> source code, right? But at the same time it's still a wiki page so anybody
> can change it. What happens when source code gets updated? The wiki and
> comments should be kept in sync, shouldn't they?

possibilities include:

(a) the wiki is totally separate. it can link back to the api auto
generated docs, those for the most part should have standard names.
(and maybe the wiki search engine would support searching backlinks
automagically for dope smokin' bonus win).

(b) it would be possible for there to be a wiki that supports
placeholder links inside auto-generated files that goes out to
standardly named wiki pages, if they exist, and/or even servers-side
includes them if they exist.

(c) something else.

[Marcelo de Moraes Serpa]

My idea is to:

1) Find out exactly how the API is generated - what tool is used, syntax etc

2) Build a tool to export it to a nice HTML GUI, with great search facilities (see railsapi.com)

    This should be automatic and based off tags in the SVN repo for the compiler, so you can check the API docs for 2.0.8, 2.0.9 etc.

3) Improve the documentation structure in haxe.org. It's confusing and provides for a bad UX. Also, I seriously think that the colors and icons used need to be replaced, they feel out of place.

   Why not borrow nice ideas from the Rails community? I think that the Rails guides is an *awesome* complement to the Rails/Ruby docs.

   Just check this simple index: http://rubyonrails.org/documentation

   

   And then check the guides: http://rubyonrails.org/documentation

  

   And for the workflow for updating the docs, check *this* out: https://github.com/lifo/docrails 

The docs fixes are 1) pushed to github and 2) published in the guides (/documentation).

We should look more outside of the Haxe circle, and I must say, the Rails community is full of creative minds, why not borrow from them? :)

   

- Marcelo

[Marcelo de Moraes Serpa]

Sorry, I didn't put the link to Rails Guides, here it is:  http://guides.rubyonrails.org/

- Marcelo

[Marcelo de Moraes Serpa]

And here's a link that explains what the docrails project is about: http://weblog.rubyonrails.org/2012/3/7/what-is-docrails/

Let's start the dochaxe project :)

- Marcelo

[Raoul Duke]

> We should look more outside of the Haxe circle

that i can't disagree with.

> and I must say, the Rails
> community is full of creative minds, why not borrow from them? :)

sure, though i haven't been in ruby or rails much at all, it seems to
be a reasonable default role model for now.

of course all this assumes somebody has the time & inclination to set
up the tooling :)

[Marcelo de Moraes Serpa]

I'm willing to help. 

Also this is very relevant to change the current Haxe documentation perspective:

"No, Ruby on Rails has no documentation project. Treating documentation as a separate aspect of the project would be similar to treating testing as an external part of the project.

Documentation is an integral part of the development of Ruby on Rails. Contributing a feature or bug fix means contributing its code, test coverage, and documentation."

If you check the Rails project, the API and "Guides" are part of the main repository (check https://github.com/rails/rails/tree/master/guides/source, it's a sinatra app that servers textile source files as HTML). Documenting is part of the coding workflow. I think this is the way to go.

- Marcelo

[Tarwin Stroh-Spijer]

What happens if you edit anything in http://haxe.org/api and then it's updated? Are the changes lost?

My main problems with the documentation is:

- API isn't documented well (examples etc)

- It's hard for new-comers (and even us oldies, if we don't keep up with the mailing list) to know what libraries are "good" and how to use them

Regards,

Tarwin Stroh-Spijer
_______________________

Touch My Pixel
http://www.touchmypixel.com/
cell: +1 650 842 0920
_______________________

[Nicolas Cannasse]

Le 24/05/2012 21:08, Marcelo de Moraes Serpa a écrit :
> My idea is to:
>
> 1) Find out exactly how the API is generated - what tool is used, syntax etc
> 2) Build a tool to export it to a nice HTML GUI, with great search
> facilities (see railsapi.com)
> This should be automatic and based off tags in the SVN repo for the
> compiler, so you can check the API docs for 2.0.8, 2.0.9 etc.
>
> 3) Improve the documentation structure in haxe.org. It's confusing and
> provides for a bad UX. Also, I seriously think that the colors and icons
> used need to be replaced, they feel out of place.
> Why not borrow nice ideas from the Rails community? I think that the
> Rails guides is an *awesome* complement to the Rails/Ruby docs.

Nice goals.

If someone can come up with a nice solution I'm perfectly fine with
redirecting api.haxe.org there.

Please keep in mind that it's not something that can be quickly hacked
then forgotten. It needs real long term support and updates or else it
will just be quickly outdated / not usable.

I've written http://haxe.org/manual/documentation to detail you what is
currently available.

Best,
Nicolas