Tried to respond inline where it made sense.
>
> 2) I Definitely agree with jKridner that the hardware assy diagram and
> the
> build instructions should be on a single card. Could you include this
> in
> your mockup? The end-user has to be able to "read and visualize" in the
> same card.
>
Agree with the same card idea.
Recently I've been playing around with Temboo, which does a nice job of
keeping the key references non-scrolling and also streamlines the user to
exactly what code they want to write. I know there's debate about TOC and
valuable space, but I think something like P8 and P9 references with wiring
might be important enough (at least for the beginning lessons).
Example:
Temboo is a service to access APIs, but they are also rolling out a section
that will "write" code for you. While I'm not suggesting Diego pursue the
code generation aspect, I am suggesting that the design of Temboo's site is
somewhat effective: Startseite - imagebin.org This image shows the main
interaction screen. The area on the far right with the misshapen Yun is
static -- think P8 and P9 here. The area with the code and drop down menus
in the center of the page does scroll and is the meat of the page. On the
left is the Temboo TOC, well a TOC of APIs. Again, this is just a reference
and I think some of it is effective.
This example looks more like an authoring screen than a
presentation/tutorial screen. I'd hope the tutorials we create could
look a bit less cluttered. Perhaps we should step back and look at
what types of things we want to teach with the tutorials and document
those? There was some of that in some of the proposals, but it
sometimes got stuck in the details of what particular sensors, etc.
I'm just wondering if we can summarize in fairly generic terms.
Examples:
* We want to show how to hook up and read/drive various passive and
active raw elements with GPIOs, such as switches, LEDs and motors
(with drive transistors).
* We want to show how to hook up and drive various elements with PWMs,
such as servo motors.
* We want to show how to configure the board to get on WiFi.
* We want to show how to flash the board.
* We want to show how to build up a simple robot.
* We want to show how to use the various functions of BoneScript.
The examples on Adafruit Learning System seem to
be a good starting point.
What aspects of Temboo's site do you most like? Do you feel like this
"card" concept is too burdensome? (Wish I could get it explained by
Adam Flaherty who first suggested it to me.)
> 3) ok, main content as .md
>
> 4) Yes, the PNG is a representation of the FZZ. They should both be
> available. The user should see the PNG by default, but it should be
> super
> easy to go into Fritzing and modify the FZZ. Should they have to fork
> first? My homework is to actually use Fritzing within the next few days
> because I havent used it yet.
Make sure you get a recent version of Fritzing and if on Debian, get an
unstable build. Recently a lot has changed with how Fritzing handles custom
parts and the parts library in general. For example, on newer builds you
don't have to manually import AdaFruit or Sparkfun's libraries.
I was just thinking of having some sort of download link for the .fzz
(if provided). I'd expect all of our tutorials to have .fzz files so
that the .png files can be updated easily by people forking the
tutorials, but I think it is OK not to *force* tutorial authors to
provide a .fzz if they just have a .jpg or .png they want to use for
the assembly diagram.
This is a tough call. I don't like the idea of forcing a specific
application, but encouraging the author to provide a layout or schematic is
important. What you don't want to instantiate is a system where someone can
get away with posting a tutorial lacking in key content.
From a structural/control viewpoint, my thinking is that people can
send pull requests to the bone101 project on Github, but it is always
up to me to decide if I want to pull them into the main, on-board and
on-main-website repository. They would essentially be copied-in (using
git submodule) only if approved, providing us with ultimate quality
control.
The gists created by users, however, would be public and could be
easily embedded on their own websites or in an "experimental only"
area of beagleboard.org. The users should always have a URL they can
share manually to point to their created tutorials even if they are
never integrated into bone101.
You'd be surprised
how far this can slide. On project pages I've edit I've encountered a
number of first time user submissions that don't divide their project into
steps via our system's step builder. The users will break out steps using
HTML tags, but not our systems step generator. While this may be a unique
situation, my perspective is certainly informed from it. My best advice is
to consider what type of workflow you are setting up for new authors and be
clear about the features of your system and how the author can leverage
them.
Authors can 'fork' existing tutorials as a quick starting point such
that they have all of the basic elements and only need to replace the
specifics. If this project is successful, they'd also be able to
follow the authoring tool that prompts them for various inputs in
order to create a tutorial gist. When their tutorial is complete, they
can use their github login and some help on our site to generate a
pull-request to the bone101 project for inclusion at
Introduction to BeagleBoard.org and eventually
http://beagleboard.org and the on-board tutorials.
>
> 5) yes, fork me.
>
> 6) lets see the new mockup with Fritzing alongside the instructions.
>
> 7) ok, force a certain image size.
Forcing an aspect ratio seems wise. Landscape allows for a page to be more
readable and it's also easier to push to print services.
I'm surprised you feel landscape is better for print, but we all seem
to be in universal support of a landscape layout.
>
> 8) Yes, Beaglebone.org should be a complete resource. Certainly we
> cannot
> expect every tutorial builder to include their own references to P8/P9
> header pinouts. There should probably be a "common area" with various
> resources that people can refer to? I have seen very simple P8/P9
> representations, but I have also seen very, very detailed versions with
> so
> much info it takes up an entire spreadsheet (Derek Malloy). It would be
> nice for people to be able to refer to these "common" resources without
> having to provide/rebuild everything themselves.
Yeah, this sounds great! It makes me think of a stock image library, but
with a much more pedagogic import than stock images.
>
> 9) On the main "homepage", it would be cool to filter the tutorials by
> Tag
> or something....so that you could find tutorials that relate to your
> interests even if you dont know the exact search terms to use. A
> tagcloud?
I think we can be more structured than a tagcloud for what goes into
bone101, but I do see having one being an advantage. Have you looked
at the filtering system at BeagleBone Black Project Spotlight: Shield I/O - BeagleBoard? I think
adding a tagcloud to help with identifying keywords could indeed be
useful. I'd personally like to try to keep the layout clear in the
gutters, but I'm open to different thoughts on that.
>
> 10) When you are in the middle of a tutorial, I was originally wondering
> if
> we wanted a "navigation menu" on the side (always), but then I realize
> that
> we do NOT want one taking up valuable screen space all the time. Should
> the
> user click "home" then get to the navigation menu?...or should it always
> be
> there? I suppose being able to jump to a certain step at any time is
> useful.?
The current mock-ups show forward-and-backward buttons. I'd also
expect there to be a show-all such that simple scrolling could be
used. Do you expect there to be so many steps that a table-of-contents
is needed for navigation?
Do all the steps need separate pages? When I'm doing a project, I typically
try and figure out how I can see all the pages in the tutorial at once
--even if this means generating a pdf.
My "show all" suggestion would mean there would be a master scroll
that would allow you to slide up and down between the steps, yet each
step would still be contained within a fix sized window (card). If
there were any software state to the cards such that one would need to
be completed before the next one began, the controls for running the
scripts could be locked-out.
Having a solid print layout seems quite necessary based on your
feedback. Just please give strong consideration (approve or reject) to
the suggestion I'm putting forward that everything should be broken
down into "cards" with a fixed layout. Not just aspect ratio, but
number of pixels, much like what you see on phone applications.
>
> 11) I am still not sold on the "looks" yet, but I have to be realistic
> about
> how much can be done with this "mockup". Jason, since the looks are so
> important to us, should DiegoTc actually start mocking up some HTML/CSS
> or
> should we stay with this "Lucidchart" conceptual approach?
The Lucidchart was a bit of a challenge for me to get a feel of the site
design; however, I'm sympathetic to this as a conceptual rendering.
How important is the site style for GSoC?
GSoC is about coding, but we care about style for people consuming the
project. No reason coding can't care about style.
I know the site design is
important for the community using the lessons, but for GSoC shouldn't we
have Diego focus on writing the lessons, not on making the lessons look
appealing?
Good point, but I feel that the lessons are a bit of the easy part
that can be sourced by the community. What the community lacks is a
good presentation platform. There are significant coding challenges in
creating the "looks good" display of tutorials placed in gist. Even
taking the existing tutorials on
BoneScript - BeagleBoard and cleaning up how they are
presented, then making them forkable, would be an excellent
contribution for the project.
Toward that end, perhaps if he works in Asciidoc or some other
clean markup for his project content, we'd be able to tweak the look and
feel of the site without too much struggle.
O'Reilly Media - Technology and Business Training is one
example of how asciidocs are used in production, and the one I'm personally
familiar with.
Why not just jump to HTML/CSS?
Perhaps forking bone101 and having Diego quickly provide us with
another version of Introduction to BeagleBoard.org that shows a
couple of tutorials "fixed up" would help us move along faster?