New doc site prototype

[Alexei Sholik]

http://alexeisholik.com/elixir-docs/modules_list.html

It's a WIP. Please don't look at index.html, it's not updated. The above link will eventually become the new index.html. Two main differences from the current site:

* no frames

* most of the things are easy to link to

Here are a couple of examples:
http://alexeisholik.com/elixir-docs/File.html#functions_summary
http://alexeisholik.com/elixir-docs/File.html#read/1
http://alexeisholik.com/elixir-docs/Kernel.html#=~/2

--
Best regards
Alexei Sholik

[José Valim]

Wow, this is very very nice! A couple notes:

1) In Ruby, it is common to have the project README (or a chosen document) as home page, which I think it is a good idea and I would like to hear your opinion. I just never got to support it in exdoc but here is an example from the Ruby community.

2) The advantage of frames (or at least how the page was structured before) is that it was very search oriented. If I was searching for a map function, I could type it in the box and quickly navigate through the four options without ever going to another page or loosing my search context. How do you think we could keep the best of both words?

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Lead Developer

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Alexei Sholik]

> 1) In Ruby, it is common to have the project README (or a chosen document) as home page

We should be able to put it somewhere. I would still want the new module summary page to be a standalone one. I'll try making Readme a default page or put a link to it in the doc header.

I will also play with the header[1] and try making it global across all pages. It could have the project name and two links: Home and Index. Home would take us to the Readme. Index would take us to the modules summary page.

Also I think it might be reasonable to place Modules, Records, and Protocols on one page, in different tabs[2]. And that page would be called Index.

> 2) The advantage of frames (or at least how the page was structured before) is that it was very search oriented. If I was searching for a map function, I could type it in the box and quickly navigate through the four options without ever going to another page or loosing my search context. How do you think we could keep the best of both words?

We can make the search field show on every page. When searching, a popover[3] with search results would appear. The search data can be put into a javascript file and sourced into every module's page.

[1]: http://d.pr/i/uYOb
[2]: http://twitter.github.io/bootstrap/javascript.html#tabs
[3]: http://adamkaump.files.wordpress.com/2011/07/popover_flatten.png

[Alexei Sholik]

Here's a small update. http://alexeisholik.com/elixir-docs/modules_list.html

I placed a header with Search on every page. The search functionality is not working yet,
but it will work like I described earlier.

Things on my TODO:

* Add support for a home page displaying Readme or some other content that describes the project in general terms.

* Make the title in the header point to this home page (instead of elixir-lang.org)

* Add table of contents with all functions/macros as a side-bar to module pages (similar to the sidebar here -- http://emberjs.com/guides/)

* Implement search on all pages

* Try adding the top-right navigation from the main elixir-lang.org site to see how it fits. (not relevant for ExDoc; specific to Elixir)

* Try displaying more context within a module page. For instance, show "Next: <link>, Prev: <link>, Children: <list>" in the path bar at the top or add a Children section before/after the moduledoc.

[Yurii Rashkovskii]

I actually like the original one that has a frame on the left. Personally I'd rather see that frame be replaced with something else while keeping mechanics of navigating that page close to what we have right now. Having to go backward all the time to fetch the index feels quite inconvenient.

By the way (this is what I experimented with a bit a few months ago), it'd be really interesting to try using bootstrap for documentation — it seems like a great candidate for this.

[Alexei Sholik]

I can try making a sidebar with the same contents the current frame has, once I implement the other stuff.

The main problems with frames are that the address bar becomes useless (it doesn't update in sync with the content) and linking to a module opens its page in a vacuum, e.g. http://elixir-lang.org/docs/master/Kernel.html

We're solving both problems by removing frames. Also, the new layout is more discovery-oriented than search-oriented: it's easier to get a high-level overview of all modules and then dig into the ones you're interested.

The search will still work globally. We can try adding a sidebar with all modules to every page too, a bit later.

[Alexei Sholik]

Also frames work horribly on mobile devices. With a sidebar, we have more options here.

[Jeremy Huffman]

I kind of agree on the frames but I did like the collapsing in the old system. Without that its more scrolling, and it kind of hits you like a wall of text.

[Alexei Sholik]

What are callbacks? If you look at the Dict module here file:///Users/alco/Documents/git/elixir/docs/Dict.html you will see it has the set of callbacks almost repeat the set of functions. But the links all point to functions (similarly, in the sidebar -- the callbacks are sorted in reverse order, but they duplicate almost all functions). And the callbacks themselves, that follow functions on the module page, only have signatures and no documents.

What are they and what's their use in the docs?

[José Valim]

A callback is a function another module has to implement in order to implement a behaviour.

The Dict provides a set of callbacks and an implementation of each function that dispatches to the proper callback, that's why it appears duplicate. The fact it appears in reverse order just means we need to call Enum.reverse or sort somewhere. :)

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Lead Developer

[Alexei Sholik]

kardan, thanks for the suggestion. I'm going for the functionality and basic usability now. The web design part will be addressed at the last stage.

Everyone, an update -- http://alexeisholik.com/elixir-docs/ (you might need to Refresh the pages to see the changes).

What's new:

* added a tentative Home page

* added top-right navigation from the main Elixir website.

* search works on all pages (please don't judge the web design side of things, it'll be addressed separately)

* replaced "Summaries" with a sidebar on module pages

On Tue, May 7, 2013 at 8:14 PM, kardan <dan...@kardans.com> wrote:

I really like the CanJS site http://canjs.com. The way the menu highlights current section is handy. Would have been awesome if it was responsive. 

Just my 2 cents - cheers

Daniel Karlsson

--

You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[meh.]

It would be nice if the list of functions in the module would follow
the scrolling, and maybe highlight the currently viewed function.

On Mon, May 13, 2013 at 01:14:56AM +0300, Alexei Sholik wrote:
> kardan, thanks for the suggestion. I'm going for the functionality and
> basic usability now. The web design part will be addressed at the last
> stage.
>
> Everyone, an update -- http://alexeisholik.com/elixir-docs/ (you might need
> to Refresh the pages to see the changes).
>
> What's new:
> * added a tentative Home page
> * added top-right navigation from the main Elixir website.
> * search works on all pages (please don't judge the web design side of
> things, it'll be addressed separately)
> * replaced "Summaries" with a sidebar on module pages
>
>
>
> On Tue, May 7, 2013 at 8:14 PM, kardan <dan...@kardans.com> wrote:
>
> > I really like the CanJS site http://canjs.com. The way the menu
> > highlights current section is handy. Would have been awesome if it was
> > responsive.
> >
> > Just my 2 cents - cheers
> > Daniel Karlsson
> >
> >
> > On Monday, May 6, 2013 2:39:51 AM UTC+2, alco wrote:
> >>

> >> http://alexeisholik.com/**elixir-docs/modules_list.html<http://alexeisholik.com/elixir-docs/modules_list.html>

> >>
> >> It's a WIP. Please don't look at index.html, it's not updated. The above
> >> link will eventually become the new index.html. Two main differences from
> >> the current site:
> >>
> >> * no frames
> >> * most of the things are easy to link to
> >>
> >> Here are a couple of examples:

> >> http://alexeisholik.com/**elixir-docs/File.html#**functions_summary<http://alexeisholik.com/elixir-docs/File.html#functions_summary>
> >> http://alexeisholik.com/**elixir-docs/File.html#read/1<http://alexeisholik.com/elixir-docs/File.html#read/1>
> >> http://alexeisholik.com/**elixir-docs/Kernel.html#=~/2<http://alexeisholik.com/elixir-docs/Kernel.html#=~/2>

[Joe Armstrong]

request:

Could you please ensure that all web-site documentation is "mobile phone" friendly.

I actually read man pages on the bus and underground (I know it's sad, you don't have to tell 

me .... get a life) on my mobile phone and it's a pain if the text is two small.

You have to do this "responsive design" stuff

Take a look at 

http://webdesignerwall.com/tag/responsive-design

Basically the acid test is just to make your web site then resize  the browser window

and make sure it looks good at all different sizes, then check on a mobile phone.

Cheers

/Joe 

[Alexei Sholik]

Thanks for your input, Joe. I'm sympathetic to your request. I too find myself reading documentation on my iPod Touch periodically. In the end we may end up using bootstrap, or foundation, or attracting a knowing front-end developer to provide the best experience we can come up with.

I would just like to say that this prototype is just that -- a prototype. I'm putting very little time in it at the moment. We still have a long way to go with both ExDoc (the tool used for extracting documentation from the source files) and the documentation site. And it's still not clear which goals the doc site should pursue first or at all: quick search, easy navigation, rich navigation, compactness for mobile suitability, etc. It'd be great to have all of them, but many of them don't fit well together.

So there are no clear plans or promises yet. Everyone's input and efforts are appreciated. As more people will start pointing out the flaws of the current design or start putting effort into fixing it, we'll get there eventually.

--

You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.