Common Cross Product Documentation

mjstn commented 2 years ago

This is a place to put suggestions for how to do cross product & cross platform documentation

Lets keep the common things in separate .md files off of learn that can be pointed to. This will require some work to separate out some of these from where they are on Magni learn today but the payoff is avoiding multiple places for this stuff.

Specifically: Batteries: https://learn.ubiquityrobotics.com/need_to_know The entire first half of this is basically common stuff so have it in separate .md file and page on learn.

WiFi Hotspot: This only 'partly applies' to EZ-Map and Breadcrumb so those will have GUI unique how to do this stuff like setup wifi on tablet stuff. We still should state in EZ-Map and Breadcrumb that you can do wifi config and test manually for ssh debug purposes so anyway the 'Connecting To The Magni Robot WiFi Hotspot' and setup of user wifi and middle of this page: https://learn.ubiquityrobotics.com/connecting

SSH Console connecting and shutdown via a ssh console can be on a page where they get slightly reworded to indicate that some product can do some of this with touchscreen or web pages so this is more of a debug mode. That too is near end of https://learn.ubiquityrobotics.com/connecting

Setup and connection of ROS laptop for RVIZ and so on. This is slightly spread around so will be some work but is a common thing.

MCB connectors and such: https://learn.ubiquityrobotics.com/mcb_pinouts_leds_userpower

MCB PC board revisions https://learn.ubiquityrobotics.com/PC_Board_RevId

out of time for meeting ... will revisit

mjstn commented 2 years ago

Vid has identified a good platform that looks great with left hand nav panel and seems quite workable for our needs.

This page at this time: https://moffkalast.github.io/learn/

I reviewed his concept pages on April 5 and they look very promising. Here is some thoughts for where to go from here:

I feel that we will be able to say many ‘generic’ things about batteries and wifi and so on in the requirements section and that looks good but is a superset. Several of these sections are in there now (for Gen5).

When we drop down into ‘configuration’ and specific things we will have to break it down. One way to do this is to introduce the concept of our Gen 5 and Gen 6 product lines. At this time we just have a main pullet point like ‘The Gen5 Platform’ then Under this a brief intro like ‘Our Generation 5 based products are our original robots and are available now to fit your needs’ (that sort of stuff but don’t say Gen6 yet). Later when we have Gen6 we add a ‘Gen6’ bullet point and discuss platform specific things like Generation 6 has been designed to scale to different sized robots with different needs’ We then can have titles like ‘Gen 5 Configuration Files’ and ‘Gen5 ROS Parameters’ in this way when we get to Gen 6 we can add next to those similar titles but with ‘Gen 6’ starting the table of contents entry on the left.

Anyway, just blue skyin here. Introduce the concept of Generation 5 but do not say anything about Generation 6 till we are much closer to that as a real product platform.

When we drop farther down into Product specific areas we can expand on ConveyorBot and the applicable pages are under that then EZ-Map and specifics on that show up under that. We should try our best to have the product pages discuss how to use products and not drop into platform specific info unless there is ‘no escape’ from doing so. In some places in product specific pages we may LATER have to say Gen5 vs Gen6 things but focus mostly on application layer interactions and abilities, not hardware debug or any low level paltform specific things there. If we have to show a picture of some switch or something fine, for now just show Gen5 but don’t say it is Gen 5 yet, that is a given.

mjstn commented 2 years ago

What we MUST do before we have 20 images crossing multiple platforms: (THAT MEANS NOW!)

We have to support multiple products and releases VERY soon. We MUST clean up our act for customer facing image distribution. Sadly I must say it is a total joke today. We need to 'grow up' so lets FIX that puny page and document our images which are about to explode in number of versions due to both noetic and EZ-Map and Breadcrumb I suggest STRONGLY we introduce a bit of 'minimal acceptable documents' for each new image.

We must fix up our extremely minimal image distribution page of https://downloads.ubiquityrobotics.com/pi.html and perhaps incorporate into other pages OR fix up this page here are my suggestions:

The main table of images should contain at least 3 columns along with some way of getting the SHA256 sum besides a massive string that wastes a lot of page space. These are the minimal columns I put out as a suggestion

Image Link (just like now is a link to download image)
Super brief comment like 'Tested working Magni production release' or 'Beta image for Ez-Map' or 'Tested working Conveyorbot release'. Keep this short and sweet for the 'intent' of the image release.
A column that says Release Notes/SHA256 sum

Each image release deserves a github file that we point to for Release notes. This file will start with again the release intent and right away at top the SHA256 sum will be stated. It can also 'grow' as we find really nasty bugs that customers really need to see. This allows us to later say 'Do not use this release unless you do not have a LeShan lidar' or other odd things we find breaks the image.

JanezCim commented 2 years ago

We need to 'grow up' so lets FIX that puny page and document our images which are about to explode in number of versions due to both noetic and EZ-Map and Breadcrumb I suggest STRONGLY we introduce a bit of 'minimal acceptable documents' for each new image.

Yes i agree, the simple download webpage has served us ok so far, but since we will have multiple images, we need to support this better.

We must fix up our extremely minimal image distribution page of https://downloads.ubiquityrobotics.com/pi.html and perhaps incorporate into other pages OR fix up this page here are my suggestions:

We could simply create a page in our learn pages that @MoffKalast is renewing now. This way we can very easily support Kinetic/Noetic images since that documentation is going to have buttons separating those. Also people will not have to navigate all over the internet to find stuff.

The main table of images should contain at least 3 columns along with some way of getting the SHA256 sum besides a massive string that wastes a lot of page space. These are the minimal columns I put out as a suggestion

Since the new documenation is going to have sepparate entries for breadcrumb/ezmap/magni/???, we could simply have each of those entries list their own "download" page. This way we would not confuse the customers that need breadcrumb documentation with ezmap images. What do you think?

Image Link (just like now is a link to download image) Super brief comment like 'Tested working Magni production release' or 'Beta image for Ez-Map' or 'Tested working Conveyorbot release'. Keep this short and sweet for the 'intent' of the image release. A column that says Release Notes/SHA256 sum

yep i like this. Maybe the super brief comment could rather be the git changelog somehow?

Each image release deserves a github file that we point to for Release notes.

If by Release notes you mean release notes from what specifically has changed with image builts, i think that is relatively easy to do. But if you mean changes since the last image has been released with ALL the software that has gone into it (single image will have multiple independent pieces of software, eg. breadcrumb, motor drivers, camera drivers, ....), that might be a bit complex since a) they live in completely separate repos b) we would have to track exactly which commit/apt version is installed on which image. Option b) is not bad, but it would require A LOT of work to do

MoffKalast commented 2 years ago

Yeah agreed, this sounds like a good idea and the kinetic/noetic wiki split should help with organization. I think I'll add a page under Overview for image downloads and we can set up the original downloads.ubiquity as a redirect to that.

With some more space allocated to each entry we can also add changelogs and other notes that Mark's had in the learn doc already for some old images.

I don't think breadcrumb and ezmap images will be on there, since they need to be private (except for ezmap_lite) but we could easily add download pages to those navbar groups if needed.

it's also great to have those entries on an easily editable page instead of some cryptic site on sfo that only a select few know how to edit.

MoffKalast commented 2 years ago

Update, we now have the images and apt repos defined in the learn doc:

kinetic images -> https://moffkalast.github.io/learn/kinetic_pi_image_downloads

noetic images -> https://moffkalast.github.io/learn/noetic_pi_image_downloads

apt repo -> https://moffkalast.github.io/learn/noetic_package_repositories

The PR can be found at #55

JanezCim commented 2 years ago

@MoffKalast should we already review the PR?

MoffKalast commented 2 years ago

Well I think the grouping should be mostly done and we do have most of the pages there for noetic, but there's still a fair few things missing. As a whole probably not yet, but it would be great to get feedback on what's already there so that can help steer what remains to be done. So feel free to comment on any entries there.

What currently remains is the lidar stuff, and all the random side pages from learn that I need to check for duplicated info and see if they need to be integrated into the new version. After that, making the kinetic copy of everything and correct the differences where applicable. (And I also need to finish the actual ezmap port from google docs)

Also I'm thinking we should probably gray out/hide the ros distro button if the specific page doesn't have a version for it, like for kinetic breadcrumb for example.

JanezCim commented 2 years ago

@MoffKalast I think all of these things will be resolved with #55 right? If yes, we can link this issue with that PR so when you merge its automatically going to close this

MoffKalast commented 2 years ago

@JanezCim Yep, sounds good.

mjstn commented 2 years ago

My comments on review of https://moffkalast.github.io/learn/ as started on May 12, today. Amazing is the top level comment. Here are things that I point people to a LOT that we need as well as pages:

A specific section under Magni Silver, perhaps just after verification in sidebar: GPIO Line Usage And it has all the info here: https://learn.ubiquityrobotics.com/GPIO_lines This is VERY popular so 'deserves' a sidebar entry of it's own. I see it 'burried' in Software Images and Micro SD flashing and it really needs to be up top front and center so perhaps in Magni Silver section next to Diagnostics and Troubleshooting with title GPIO Line Usage.
The 'General Info' can say 'General and Mechanical Info' (Very often we get people asking for the mech info so just in 'General' is too 'hidden'. But the page there is great, just say 'Mechanical' along with 'General' in sidebar
Firmware Update is also a top page I point people to and should have it's own point under 'Magni Silver' for ease of finding it. It would have all the info in https://learn.ubiquityrobotics.com/firmware-upgrade You do have this under the MCB section but it is so important and so popular it would help people to rip it out off the MCB and right under MCB have a left panel bullet of 'Firmware Upgrades' or some such with a separate page. We could argue this from an esoteric standpoint but the reality of the matter is humans get lost in submenu searches so if it is right to the left they see it far easier, less frustration for super popular topics basically.

MoffKalast commented 2 years ago

A specific section under Magni Silver, perhaps just after verification in sidebar: GPIO Line Usage And it has all the info here: https://learn.ubiquityrobotics.com/GPIO_lines

Now that I compare the content, I think all of that is basically the new Raspberry Pi page with some extra introductory info about the Pi. Perhaps we could rename that to be more indicative, but since this is a Pi hardware thing I would think it fits where it is?

The old link https://moffkalast.github.io/learn/GPIO_lines also redirects there.

The 'General Info' can say 'General and Mechanical Info'

Agreed, as a tutorial example, you can try changing that yourself by doing the following:

find the page, click the Edit on GitHub button on top
change the header param of title: "General Info" to the new title
optionally, edit the title label # General Information to show the same text
go back to the original page, change the slider to Kinetic/Noetic and repeat for the other version

Firmware Update is also a top page I point people to and should have it's own point under 'Magni Silver' for ease of finding it.

Okay I suppose that can be separate, but we should label it as Firmware Update (MCB) since swapping the Pi SD card is technically also a firmware update.

I'll make the edits this time since it's easier with a cloned repo, but as a reference the process for adding a page would be:

create a new md file in learn/noetic/magnisilver

copy over the header from one of the other magni silver files as for example the following:

---
title: "Motor Control Board (MCB)"
permalink: noetic_magnisilver_mcb
group: "magni silver (gen 5)"
rosver: noetic
nav_order: 3
nav_exclude: false
---

change the permalinkto something unique that follows convention, e.g. noetic_magnisilver_mcb_update, and update the title
decide where in the navbar group the page should appear, I'd say right below the MCB entry, so that would make the nav_order: 4
change the nav_order in all pages that come after it (basically increment each by one)
repeat for kinetic/noetic as before

mjstn commented 2 years ago

Thanks for considering these inputs. I do realize that firmware update would 'ideally' be under MCB but frankly we are HELLA long ways from shipping Gen6 (OH! Did I just say that???). Firmware update is a top level product exposed process. So I am at a loss as to how to do this but in the end we may end up with 'Firmware Update' and then in THAT link have to say 'Here is what to do for Gen5, Here is what to do for Gen6'. this is an interesting point. We battle with presentation of processeses at the product level vs super high level 'How to update firmware' which branches ALL platforms. There is no ideal solution but I lean towards 'How to update Firmware' is on the sidebar and then below that 'Here is how to do it on Gen 5 and here is how to do it on Gen 6'. Mind you, on Gen6 we are going to have 3 or so firmwares so that is yet another level of abstract documentation organization.

My highest level point is as we go from Gen 5 to Gen 6 we must place ourselves in the CUSTOMER mindset who does not give a crap which Gen he is on. he just wants answers with as few clicks as possible.

We face this root decision: Make it easy for customers to support the product vs make the documents all branch down from Gen 5 or Gen 6. I greatly lean to 'make it easy for customers to do high level operations'. The will ALL have to do firmware updates and image updates. To me THAT is the top level and branch down to what the hell Gen they have after that.

We are discussing ease of customer support on Learn and we are NOT discussing 'nicely organized docs on a given platform'.

You don't have to believe me but please thing in the customer mindset who just has this damn box and wants to update image or product (magni vs breadcrumb vs EZ-Map) or update firmware. All are equally of importance and must branch BELOW the fundamental need of the customer. We tell them 'Be sure your firmware is current' that must translate to ONE link on the left and then filter down to specific product types after that.

This is about ease of support and minimizing customer support searching for crap. This is NOT about anally nicely organized product documents.

I do feel that full docs on a given product are of importance but learn is most ALWAYS used to find a solution so when we get to Gen6 we have to not confuse the hell out of customers.

This is really tricky and there is no absolute. I share here that my view is to make support easy to the customer.

mjstn commented 2 years ago

Maybe we need a verbal chat this week. This sort of contorted discussion falls apart in text replies.

MoffKalast commented 2 years ago

So I am at a loss as to how to do this but in the end we may end up with 'Firmware Update' and then in THAT link have to say 'Here is what to do for Gen5, Here is what to do for Gen6'. this is an interesting point.

Hmm right, we could put that as an overview page, since the actual update page should probably be in the Gen 6 nav group when we end up making it.

The way I set up the nav grouping is something along the lines of this:

Overview (most important (and if possible robot agnostic) things like requirements, batteries, images, etc.)
Gen 6 (everything related to the physical robot like unboxing, assembly, sensor mounting...)
Gen 5 (again everything concerning the physical robot)
Quick Start (all robot-agnostic software, like pifi, ros, move_basic, mapping, etc.)
Product Stacks (separate nav groups for Conveyorbot and EZ-Map specifics or whatever we come up with next)

So we probably should put the most in-demand pages into Overview I suppose, or at least links to them so they're easy to find. For example robot images should've been in Quick Start by the general grouping logic, but it's more convenient to have them at the top.

It might make sense to rename Overview to Quick Start and Quick Start to Software or something like that, but it's hard to say what's best without some actual customer feedback.

a verbal chat this week

Before or after one of the huddles I suppose?

mjstn commented 2 years ago

Vid and I went over this interactively for a few points.

I feel this is READY TO GO LIVE! Nicely done Vid!

JanezCim commented 2 years ago

yes, good work :)

UbiquityRobotics / learn

Common Cross Product Documentation #51