LeafLabs Garden

A place to share, learn, and grow...

1. 

   mbolivar
   LeafLabs

   Hey everybody,

   As you may have noticed, we've been revamping all of our technical documentation in the newdoc branch of the libmaple repo. This addresses bugtracker issue 21:
   http://code.google.com/p/leaflabs/issues/detail?id=21

   While the new docs still desperately need some custom "LeafLabs" layout and CSS (which they'll be getting over the next couple of days), their content is done. We've put a preview up here:

   http://static.leaflabs.com/pub/leaflabs/maple-docs/docs-0.0.9-preview/

   Looking for any comments/suggestions/corrections you may have to offer.

   There are some things in particular we're looking for feedback on:

   1) The quickstart:

   http://static.leaflabs.com/pub/leaflabs/maple-docs/docs-0.0.9-preview/maple-quickstart.html

   2) The language reference:

   http://static.leaflabs.com/pub/leaflabs/maple-docs/docs-0.0.9-preview/language.html

   3) The individual core language function reference pages. E.g., here's analogRead():

   http://static.leaflabs.com/pub/leaflabs/maple-docs/docs-0.0.9-preview/lang/analogread.html

   These are scheduled go live on December 15th along with libmaple and Maple IDE 0.0.9, but your thoughts are welcome anytime.

   Posted 5 years ago #
2. 

   soundcyst
   Member

   nice.. looks phythony.. (i suppose sphinx has a bit to do with that ;)

   i'll definitely be more detailed and constructive when i receive my board and start tinkering..

   Posted 5 years ago #
3. 

   mbolivar
   LeafLabs

   ha, yeah, right now it's just the default sphinx theme, which is what's used for the python docs. we'll likely be styling it away from that.

   on that note, how do people feel about the sidebar? i'm a little ambivalent, myself.

   sphinx has been great for us, by the way, if anyone's in the market for a docs build system.

   and soundcyst -- if you ordered from us, and you're in the US, your board shipped out today. international orders are going out tomorrow.

   Posted 5 years ago #
4. 

   gbulmer
   Moderator

   mbolivar - I've had a quick scan. This documentation looks very good! Well done to all.

   I think it looks a bit odd having the 'contents' of the page in both the side-bar and the page itself. If the side bar 'moved' to always stay visible when the page is scrolled, then the side-bar would be the way to go, but as it doesn't, it just seems odd to have the same stuff twice. I am left feeling like it may be annoying to lose the width of the side bar from the window. I have a reasonable size screen on my laptop, but it might be more of an issue on a netbook, or iPad:-)

   I'll have a bit more browse over the next few days.

   Posted 5 years ago #
5. 

   crenn
   Moderator

   http://static.leaflabs.com/pub/leaflabs/maple-docs/docs-0.0.9-preview/spi.html

   It doesn't mention that SPI1 can't go at the slowest speed, doesn't tell you about the single byte send function and what data is returned from them. Although thinking about it, I should write a small tutorial/begineer's guide on how to use SPI including explaining out all of the settings.

   Posted 5 years ago #
6. 

   mbolivar
   LeafLabs

   gbulmer -- our original plan was to remove the sidebar before the final release, mostly for the screen real estate issue you mention. we do browser testing on a 1024x768 resolution monitor, as that seems to be the smallest size that's still in reasonably widespread use. at that resolution, the sidebar does hurt, especially with the font size as large as it is.

   it seems like people would prefer a sidebar, though. sphinx supports a 'sticky' sidebar which follows the visible portion of the window; if it works well across browsers, we'll likely go with that, and remove all of the tables of contents.

   crenn -- thanks for the corrections. they'll be fixed before final release.

   thanks for the feedback so far! it's very helpful.

   Posted 5 years ago #
7. 

   crenn
   Moderator

   If the side bar is going to be kept, can I recommend something like this:

   Usage Guides:
   -Quickstart Guide
   -Firmware flashing
   -IDE installation

   Maple Programming:
   -Arduino Compatibility
   -Maple Functions

   Hardware features:
   - I2C
   - PWM
   - GPIO
   - USB
   - JTAG
   - ADC
   - SPI
   - USART
   - Timers

   Just an idea.

   Posted 5 years ago #
8. 

   mbolivar
   LeafLabs

   just posted the first attempt at a restyle. no content corrections yet. crenn, that's an interesting suggestion; something like that seems like a good idea.

   Posted 5 years ago #
9. 

   crenn
   Moderator

   The restyle looks pretty good, curious why the side bad is now on the right.

   Posted 5 years ago #
10. 

    mbolivar
    LeafLabs

    i think it's just where the theme we're customizing puts it (not sure; i didn't do the theming), but i think it's nicer there.

    Posted 5 years ago #
11. 

    crenn
    Moderator

    To me it looks a little strange, but that's all.

    Posted 5 years ago #
12. 

    larryang
    Member

    I would round some of the corners (that seems be the trend nowadays). Makes it feel less, um, harsh. Color scheme works for me.

    Posted 5 years ago #
13. 

    mbolivar
    LeafLabs

    larryang -- yeah, that's a good idea.

    Posted 5 years ago #
14. 

    hanna
    Member

    crenn -- I've been putting together the restyle. I can't stand having to go back to a separate table of contents page all the time when I'm looking at documentation, so I'm definitely a fan of the sidebar. I hope you (and other sidebar naysayers) grow to like it, but I'll look into making it collapsable anyway.

    larryang -- I'll do what I can, but it's going to be hard to round anything out without writing a new template all together. I tried to soften it up by handpicking friendly fonts. Please let me know if you have any more ideas for making the interface less harsh.

    I'm the newest member of LeafLabs by the way. It's nice to meet you all!

    Posted 5 years ago #
15. 

    crenn
    Moderator

    Hanna, I'm not saying the sidebar is a bad idea, I'm saying it looks strange on the right to me.

    Posted 5 years ago #

RSS feed for this topic

Reply »

You must log in to post.