Restructure docs, part one: nav and landing pages #258

WasabiFan · 2016-09-29T19:04:37Z

Update nav structure
Add networking landing page
Add low-level driver access page
- Pretty basic; would ideally be expanded on later.
Re-did docs landing page
Added descriptions and proper sort to tutorials page
Fixed misc small style issues

Live at http://wasabifan.github.io/ev3dev.github.io/.

Fixes #246
Fixes #244
Fixes #243
Fixes #242

…nto restructure-docs

Fixes #242

WasabiFan · 2016-09-29T22:08:43Z

I think I need to add the networking landing page to the documentation nav item.

WasabiFan · 2016-09-29T22:11:40Z

I also need to mark on the "networking" page which tethering options are supported on what platforms. And probably make the warnings bold.

WasabiFan · 2016-09-29T22:12:24Z

Oh, and I need to update Getting Started for these new pages (mostly networking).

dlech

Thanks for doing this. Overall, I like the direction you are going here.

dlech · 2016-09-30T00:04:01Z

docs/tutorials/nxtmmx.md

@@ -1,6 +1,6 @@
 ---
 title: Using the mindsensors.com NxtMMX Motor Controller
-subject: Hardware - Motors
+subject: hardware-motors


How about renaming subject: to group: since these are linking to the tutorial-groups.yml data?

dlech · 2016-09-30T00:05:18Z

docs/tutorials/index.html

+<p class="lead">
+    These tutorials will walk you through working with a wide range of hardware and
+    software. If you're looking for help with a specific goal, this is the place to
+    look!


It might be nice to mention that anyone can contribute tutorials if they have something useful to share.

Are tutorials meant only for hardware and software or are other concepts welcome?
This dertermines also what people will think they can contribute.

I mean for example:
Robotics - Odometry
Robotics - Motion Control
Kalman Filters, SLAM, etc.

E.g. with ev3dev example realization

I think that the tutorials should generally be focused on technical things that one might want to do with ev3dev which are specific to our platform. In general, I want to keep the number of "novel but tangential" tutorials to a minimum. It's a fine line, though; for example, I really like the LIDAR and RasPi camera ones, but I would rather not have generic "robotics" tutorials like odometry as a whole. That type of thing is probably better suited for a project page.

dlech · 2016-09-30T00:10:28Z

docs/networking.md

+
+### With a Wi-Fi dongle
+
+The simplest route is to purchase a Wi-Fi dongle and plug it into the EV3's USB


I disagree that this is the simplest. You have to do research to find a compatible adapter and then buy one.

I think we should list USB first since virtually everyone has USB, whereas not so many people will have a WiFi adapter laying around.

If you have a Wi-Fi dongle (e.g. the LEGO-compatible one), I think Wi-Fi is the simplest. If you don't, USB will be the easiest as you mentioned. The reason that I put Wi-Fi first was because Windows has issues with USB sharing (you frequently have to disable and then re-enable the option).

How does this sound: I reword and restructure this so that it says something to that effect. If you have a Wi-Fi dongle, use it; otherwise use USB.

Hmm... I wasn't considering the Windows ICS issues.

My personal preference would be to connect by USB first then use connmanctl to enter my wifi password because it is insanely long. But I imagine I am the exception here.

I'll let you make the call here.

I would second @WasabiFan here.

Whatever you do you will likely endup using Wi-Fi. Or just most people will.

Other means of connection are great if one can't use Wi-Fi for some reason (USB host used by something else, no dongle yet, no driver for dongle, etc).

dlech · 2016-09-30T00:16:06Z

docs/networking.md

+### With a Wi-Fi dongle
+
+The simplest route is to purchase a Wi-Fi dongle and plug it into the EV3's USB
+port. Almost any USB Wi-Fi dongle which supports Linux will work, including the


This could be misleading. Many dongles that "support Linux" have a vendor driver that you have to compile yourself, which is beyond most people. "Many" would be more accurate than "Almost any".

I think we should start recommending the dongles that are supported by the official LEGO software as officially supported by ev3dev.

Can you point me to a list of supported ones? I know of the Netgear one, but I was unaware that there were others that they supported. And are there any other dongles that you think are common and known to work that I should include?

The "officially supported" ones are going to be the ones I actually own.

0846:9030 NetGear, Inc. WNA1100 Wireless-N 150 [Atheros AR9271] 7392:7811 Edimax Technology Co., Ltd EW-7811Un 802.11n Wireless Adapter [Realtek RTL8188CUS] 0bda:8176 Realtek Semiconductor Corp. RTL8188CUS 802.11n WLAN Adapter

The first two are the ones officially supported by LEGO.

The last one is this except mine has Dexter Industries branding. It works with the official EV3 firmware as well.

Sounds good; I'll add that.

dlech · 2016-09-30T00:17:01Z

docs/networking.md

+
+If you have a USB Ethernet adapter (or can buy one) which supports Linux, you
+can use it to access the network from your EV3. Just plug it into the brick and
+connect the adapter to an ethernet cable; no configuration is related.


do you mean "no configuration is needed"?

Damn autocorrect 😆 I enabled a spellcheck extension for editing Markdown on the site, but apparently it got a bit overzealous after I mistyped something. Thanks for noticing!

dlech · 2016-09-30T01:18:26Z

docs/driver-access.md

@@ -0,0 +1,26 @@
+---
+title: Low-level driver access


Having "Low-level" in the title and subtitle is redundant. I like "Hardware Drivers" for a title.

Also docs/drivers.md would be a more generic (future-proof) file name.

/docs/drivers is the path to our index of drivers (literally a list of driver pages). I think the "driver index page" is an important page to have, but I didn't want to have that list thrown in with this content, so I attempted to come up with a creative title and URL for this one. How do you think we should handle this?

/docs/drivers/overview maybe?

or /docs/driver-overview

dlech · 2016-09-30T01:21:48Z

docs/index.html

+            have not been migrated from our old wiki yet. We'd love some help
+            with getting these last few pages migrated! If you would like to
+            help out, read more about what's needed in the
+            <a href="../contribute#write-some-documentation">documentation section</a>
            of our "contributing" page.
        </p>
    </div>
 </div>

 <h2>System setup</h2>


"Installation and Setup" might be a better title.

dlech · 2016-09-30T01:23:14Z

docs/index.html

-        <a href="drivers">ev3dev kernel drivers</a>
-    </li>
-</ul>
+<h3>Low-level driver access</h3>


Everything else on this page is <h2>

I was imagining this nested under "writing some software." Do you think it should be structured differently?

I don't think of hardware drivers as writing software. I refer to those pages often just to get technical info on sensors.

dlech · 2016-09-30T01:25:54Z

_includes/header.html

@@ -42,7 +42,10 @@
                        </ul>
                    </li>
                    <li>
-                        <a href="/news" title="News about ev3dev">News</a>
+                        <a href="/support" title="Get Help">News</a>


This should not say "News"

I'm not sure what's more worrying: the fact that I made the mistake in the first place, or the fact that I have been staring at a header with two "news" items for the past week without noticing 😊

dlech · 2016-09-30T01:27:29Z

_includes/header.html

-                            </li>
-                            <li>
-                                <a href="/share" title="Share projects that use ev3dev">Share</a>
+                                <a href="/projects" title="Discover projects that use ev3dev">Project showcase</a>


For some reason, I feel like this should be the last item on the list (and Contribute should be first). Just intuition I gues.

I think this depends on what the "projects" page becomes. If we expand it to be a full-fledged "examples" hub, the link to that (which may be the same page or different) should definitely be obvious. As it is now though, I'll flip it around.

- List supported Wi-Fi dongles - Reorder options to favor simplicity - Rephrase odd sentences

…nto restructure-docs

WasabiFan · 2016-10-03T04:38:35Z

I think I've updated everything based on feedback, aside from two things which I commented on (I wasn't sure if there were any action items from those two). Preview site updated as well.

bmegli · 2016-10-03T07:45:59Z

docs/tutorials/connecting-to-ev3dev-with-ssh.md

@@ -1,6 +1,6 @@
 ---
 title: Connecting to Ev3dev Using SSH


I know the reason but this capitalization looks strange (Ev3dev)

Shouldn't it be ev3dev instead?

This is the "new grammar" as I have taken to calling it 😆 The issue is that we have a tradeoff between not capitalizing it (even though it is title case) and capitalizing it weirdly as you pointed out. So, we're looking at this:

Doing Stuff with ev3dev

Doing Stuff with Ev3dev

Both look wrong. One is more grammatical, the other may look better. We opted to standardize on the latter option, but honestly I don't have much of a preference either way.

The logo on the site seems to suggest Doing Stuff with EV3DEV

I think that's a stylistic choice for the logo instead of a grammatical one. Personally, the only potential options that I think are explicitly incorrect are EV3DEV and EV3dev.

Smallcaps? ᴇᴠ3ᴅᴇᴠ 😺

😖 This confuses my brain

bmegli · 2016-10-03T07:48:24Z

_data/tutorial-groups.yml

+    description: "Guides on flashing an SD card with ev3dev images."
+  - id: system
+    title: "Ev3dev System"


Hmm, Ev3dev capitalization looks strange.

It seems like the small letter became part of the name but maybe that's just for me.

bmegli · 2016-10-03T07:49:45Z

docs/tutorials/upgrading-ev3dev.md

@@ -1,6 +1,6 @@
 ---
 title: Upgrading Ev3dev


again, I understand the reason of capitalization...

Again the same feeling that it should be ev3dev

bmegli · 2016-10-03T08:24:29Z

docs/networking.md

-If you have a USB Ethernet adapter (or can buy one) which supports Linux, you
-can use it to access the network from your EV3. Just plug it into the brick and
-connect the adapter to an ethernet cable; no configuration is related.
+The simplest route is to use a Wi-Fi dongle connected through the EV3's USB


How about: "The simplest route is to use a USB Wi-Fi dongle"

Anyway, all of that assumes that poeple have some acces point/router with AP available.

So how about:

If you have access to the Wi-Fi network the simplest root is to use a USB Wi-Fi dongle.

Good idea, I'll change that sentence.

bmegli · 2016-10-03T08:35:44Z

Some things that need fixing but that were not introduced in this pull (I list them to rember):

Edit: I can open a pull to your pull or fix that later

"Step 2: Copy the image on to the SD card"

Shouldn't it be "Step 2: Copy the image to the SD card" ?

"For Raspberry Pi you will need to use the wired Ethernet connection first."

Should probably be:

"For Raspberry Pi you will need to use the wired Ethernet connection or a display & keyboard first."

"All not saved data may be lost" (sounds awkward)

Should probably be:

"The data that was not saved may be lost"

", but way easier to enter you passphrase this way"

Should probably be:

", but it's way easier to enter you passphrase this way"

In my language it's ok to not use verbs (we have implicit verb construct) but they taught me that it's not ok in English ;-) (yes, I am also doing that in English...)

WasabiFan · 2016-10-03T14:24:30Z

Shouldn't it be "Step 2: Copy the image to the SD card" ?

Honestly, I'd prefer "Step 2: Flash the SD card with the downloaded image".

Should probably be: "For Raspberry Pi you will need to use the wired Ethernet connection or a display & keyboard first."

Assuming that's technically correct (which I believe it is), I like it.

Should probably be: "The data that was not saved may be lost"

I like "All unsaved data will be lost", although depending on where you are seeing this, it may be better as "All data that you have not backed up to another location will be lost".

Should probably be: ", but it's way easier to enter you passphrase this way"

Good catch, although we should also fix the "you": it should be "your".

WasabiFan · 2016-10-03T14:26:15Z

In my language it's ok to not use verbs (we have implicit verb construct) but they taught me that it's not ok in English ;-)

I have to say, I can't imagine how that would work 😕 Either way, you're correct in that it's not applicable in English.

dlech · 2016-10-03T15:53:13Z

Honestly, I'd prefer "Step 2: Flash the SD card with the downloaded image".

Keep it short. "Flash the SD card" will do.

Assuming that's technically correct (which I believe it is), I like it.

If you want to get technical, it would be a device without a display, so BrickPi on RPi. PiStorms on RPi has a display.

I like "All unsaved data will be lost", although depending on where you are seeing this, it may be better as "All data that you have not backed up to another location will be lost".

+1 for using the word "backup"

bmegli · 2016-10-03T16:47:39Z

I mean that sentence from the docs:
"For Raspberry Pi you will need to use the wired Ethernet connection first"

If you want to get technical, it would be a device without a display, so BrickPi on RPi. PiStorms on RPi has a display.

It's in the context of Get Started. All Raspberry PI versions have video output. Technically speaking user doesn't have to use Ethernet. He can plug the display/keyboard and configure whaterver network connection he wants (e.g. WiFi, bluetooth).

[...] implicit verbs [...]

Hmm, I messed it. We have implicit subject that can be reconstructed from the verb form.

dlech · 2016-10-03T17:00:19Z

All Raspberry PI versions have video output.

And when you use PiStorms, you will not get a terminal on the built-in video of the RPi by default, so it is not much use.

bmegli · 2016-10-03T18:50:02Z

@dlech written:

And when you use PiStorms, you will not get a terminal on the built-in video of the RPi by default, so it is not much use

Uhmmmm, agreeed but...: ;-)

In the docs we have:

_For Raspberry Pi you will need to use the wired Ethernet connection first._ With PiStorms the EV3 options will work too since you have a screen to configure them on.

Which is not true. For RPi/BrickPi you can use screen/keyboard to setup any connection you like without ethernet connection (Wi-Fi, bluetooth, XBee, ZigBee, whatever)

So something along the line is technically correct:

For RasberryPi/BrickPi you can use wired connection or setup other connection using screen and keyboard. With PiStorms the EV3 options will work too since you have a built-in screen to configure them on.

bmegli · 2016-10-03T19:04:28Z

Or:

For RasberryPi you can use wired Ethernet connection first. With PiStorms the EV3 options will work too since you have a built-in screen to configure them on. With BrickPi you can also setup other connection from the console using external screen and keyboard.

WasabiFan · 2016-10-04T23:33:53Z

@bmegli I think I understand your point, and I agree; if you'd like to open a PR with that extended sentence I think it would make it clearer and we could merge it from there.

@dlech In case it was lost in the discussion, I updated the PR with fixes for the issues you pointed out. There were two that I was unsure on (they appeared to be planning instead of changes) which I didn't handle.

dlech · 2016-10-05T00:20:40Z

docs/getting-started.md

@@ -130,7 +130,7 @@ Now it's time to write the image to the card.
 <div class="alert alert-info" markdown="1">
 {% include icon.html type="info" %}
 For more detailed information and more alternatives, check out
-[our other tutorials](/docs/tutorials/#group-sd-card-image){: .alert-link }.
+[our other tutorials](/docs/tutorials/#group-administration-and-setup-sd-card-image){: .alert-link }.


I think you forgot to delete the -sd-card-image part.

The ID is composed of the group name and the subgroup name, so this is correct for the current behavior. The CI server checks complained at me after I changed the tutorial page because I had forgotten to update this link, but now it's happy that the link is valid.

dlech · 2016-10-05T00:23:00Z

docs/networking.md

@@ -0,0 +1,83 @@
+---
+title: Networking
+subtitle: Connecting ev3dev to the internet and other devices


This should be Title Case.

dlech · 2016-10-05T00:23:50Z

docs/driver-overview.md

@@ -0,0 +1,26 @@
+---
+title: Hardware Drivers
+subtitle: Controlling ev3dev devices through the low-level driver APIs


Subtitle should be Title Case. (It is still a title after all 😉)

Actually, I didn't look to see if we are doing this on other existing pages.

I believe most of our pages use a sentence-case subtitle currently (e.g. http://wasabifan.github.io/ev3dev.github.io/news/). I personally like this style, for reasons similar to why many news organizations are now sentence-casing their titles: it seems more conversational.

dlech · 2016-10-05T00:25:08Z

docs/networking.md

+on your EV3, you'll need to connect to a network. Here are some resources to
+help you out.
+
+# Connecting to the internet


<h1> headings really should be title case as well.

WasabiFan added 13 commits September 22, 2016 19:21

Update nav structure to better-prioritize links

da59d7a

Add networking landing page

61e45da

Merge branch 'master' of https://github.com/ev3dev/ev3dev.github.io i…

d528ccf

…nto restructure-docs

Add ethernet option to networking page

8b29e75

Add basic driver overview page with TODO content

2f79c16

Wrap networking page to 80 chars

4ac0986

Merge branch 'master' of https://github.com/ev3dev/ev3dev.github.io i…

47bd5a5

…nto restructure-docs

Add link to new SSH page

26a22fd

Partially update docs landing page

0e3a0f2

Restructure tutorials homepage (fixes #243)

713d0a6

Fix IDs on tutorials page and add highlight effect

7ad9bdb

Fix edit button alignment with long page titles

52800ca

Mostly finish docs and driver pages

9d1b6cf

Fixes #242

WasabiFan added the documentation content label Sep 29, 2016

WasabiFan mentioned this pull request Sep 29, 2016

Nigel's generic comments ev3dev/ev3dev-lang-python#222

Closed

dlech reviewed Sep 30, 2016

View reviewed changes

WasabiFan added 9 commits September 30, 2016 11:06

Re-organize tutorial groups and rename attributes

651366c

Rename "Libraries" to "Programming Languages"

ef690ae

Update networking page

08324f2

- List supported Wi-Fi dongles - Reorder options to favor simplicity - Rephrase odd sentences

Rename driver page and remove code in link

58f98cf

Stop calling SD card tutorials "deprecated:

0d38e85

Update header organization and other links

7c8ac73

Fix broken links to tutorials and libraries pages

330a8f9

Merge branch 'master' of https://github.com/ev3dev/ev3dev.github.io i…

9ed975d

…nto restructure-docs

Fix broken link in LIDAR tutorial

af3aaab

bmegli reviewed Oct 3, 2016

View reviewed changes

dlech mentioned this pull request Oct 4, 2016

Create supported-wi-fi-adapters #157

Closed

dlech requested changes Oct 5, 2016

View reviewed changes

Capitalize top-level headings

14cc6d3

dlech approved these changes Oct 6, 2016

View reviewed changes

Add networking page to docs header

465c161

WasabiFan merged commit 0eb9851 into master Oct 7, 2016

WasabiFan deleted the restructure-docs branch October 21, 2016 04:05


		### With a Wi-Fi dongle

		The simplest route is to purchase a Wi-Fi dongle and plug it into the EV3's USB

Restructure docs, part one: nav and landing pages #258

Restructure docs, part one: nav and landing pages #258

Uh oh!

Conversation

WasabiFan commented Sep 29, 2016

Uh oh!

WasabiFan commented Sep 29, 2016

Uh oh!

WasabiFan commented Sep 29, 2016

Uh oh!

WasabiFan commented Sep 29, 2016

Uh oh!

dlech left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dlech Sep 30, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dlech Sep 30, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dlech Sep 30, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

WasabiFan commented Oct 3, 2016

Uh oh!

Choose a reason for hiding this comment

dlech Sep 30, 2016 •

edited

Loading

dlech Sep 30, 2016 •

edited

Loading

dlech Sep 30, 2016 •

edited

Loading

ddemidov Oct 3, 2016 •

edited

Loading

bmegli Oct 3, 2016 •

edited

Loading

bmegli commented Oct 3, 2016 •

edited

Loading