Honestly though, I think any one of these can be used to meet those needs. Each of them could use some tweaking. But I think you are selecting between several winning options.
Good idea, I can slide that down and replace it with the static image like the rest.
A- Oh, year 7 years is something to be very proud of.
d- A link to the updates section is probably a good idea. I usually only use the blog feature for larger stuff. Or I can start using the blog more…
e- the summary, catchphrase, or similar. I get it I think. If I can get the sections good I can add more details to each one. I think you can see some I do have a little boasting about the users. I liked that and wanted to do more.
Yeah super not easy. It is all there but it is kind of like it’s own programming language for each one. They all label things different and to try them out I have to add words and pictures. The whole time I do it, it is flashing and refreshing to WYSIWYG my changes. Pretty rough on the eyes. Only a few hours at a time, last night one eye literally started twitching.
I think it is getting close, then we can really dial it in. I kinda miss programming my own page, in the end it was easier. (must be what Linux users feel about all the clicking in the windows gui)…
You can easily spend as much time on this as you want, and it will still be getting better. That’s the real work. It isn’t magic, it is labor.
Yeah. I would try to lean back in your chair and look at the site and see if that perspective “feels” right for V1Engineering. Adding people to the images is something that would add to this feature for me. Because it is about the process and it is about the people. I know that is super hard, and I like the steps you’ve taken (“The Best Users” … “Make the Best Projects”). Is there a way to make a close in, slo-mo shot of someone’s hands while they are installing a bearing, or sliding a truck on a tube or something?
I’m being very optimistic with what can be done. I know this stuff is a lot harder than it looks.
1 Like
I love the ideas. Definitely at least get some hands in there. I would love to get someone…maybe even me.
1 Like
Its when you start to drool that you have to stop 1😅
1 Like
P.S. I am still chipping away at this. https://0p7fw9nx7p9w91qj-15662831.shopifypreview.com
A lot of it is placeholder and editing and new pictures need to happen. For all the small things I do not like I have a friend from my Robo days that can help with the Shopify theme editing.
@vicious1, @jeffeb3 and/or others, [http://forum.v1engineering.com] uses Discourse.org, can you configure with CORS enabled for requests originating from docs.v1engineering.com?
Since build doc markdown can contain javascript (e.g. LR3 Calculator), am wondering whether build docs could also contain javascript that uses forum’s Search APIs to markup Build Doc steps with additional context/links if/when Maker needs hints (beyond the build step text) on how to proceed.
Example of why/why-not, risks, and how to enable CORS is available at:
- Set DISCOURSE_ENABLE_CORS for hosted forum - hosting - Discourse Meta
- What are the risks of enabling Cross-origin resource sharing (DISCOURSE_ENABLE_CORS) - support - Discourse Meta
If you decide to enable CORS, then CORS would need to be enabled, AND, http://docs.v1engineering.com and https://docs.v1engineering.com need to be added to “CORS origins” field, don’t add wildcard. Am unit testing with mkdocs running locally on http://docs.v1engineering.com:8000 (where docs.v1engineering.com resolves to 127.0.0.1 on my Dev Box), I don’t think enabling another origin for the 8000 port is needed, but I could be wrong, we’ll see…
Discourse Settings → Security → CORS origins
Reason I ask… Wondering whether Maker build experience can be improved by helping to close the gap between specific documentation steps, and related forum topics. Goal is maximize joy by reducing time to understanding, reduce repeated questions on the forum, increase context associated with trickier build steps without Ryan having to update the doc.
Currently, topics can have tags scoped to specific projects. Topics can contain links to specific build steps. But Build Documentation readers are currently oblivious as to how many questions have been asked relating to a given build step, in a way that’s easily discoverable, directly from the build step they’re currently working through.
Thinking that adding some code to the docs can help auto markup header for each section with additional ‘badges’ that link to forum, video and maybe other actions (?) that enable Users to quickly dig deeper and self help if/when they’re stumbling on a specific step.
Imagine the following example, but with search hit numbers in the “forum” notification badge. Hover/Clicking reveals popup that opens related forum Topics. Need APIs to work from docs.v1engineering.com to enable this scenario.
If interested to see more, enable CORS and I’ll try to share a pull-request/prototype.
Alternative options that don’t involve enabling CORS…
- Create scheduled task to periodically query forum APIs, generate and publish index/metadata to somewhere that Build Docs can access and render. Data will be as stale as the time between run intervals. Less, and smaller request payloads.
- Create a service to proxy API requests in a way that doesn’t care about CORS policies of upstream API. Involves burning time creating and maintaining another thing.
I am hosted on both sides. Gihub.io and discoursehosting.com. Would that still work.
I have not had enough coffee yet, but I will look at this again in a bit.
I do not have full admin control of the forums, but I can make requests.
Our current situation, my main goal is keeping track of how often something gets asked here (and FB, reddit, etc). If something gets asked multiple times, I try and edit the docs to contain any missing information. We have the added cheat here of autolinks (test crown), to point to a docs page. What I think would really help is a troubleshooting flow chart in the docs, but that has proved to be very difficult.
I will make two counter arguments. But I don’t know if they outweigh the potential benefits:
- Keeping the docs as close to pure markdown as possible really helps keep them future proof. Any html or js we add won’t work if we convert them to jekyl or readthedocs, or pdf. We already have made this compromise a couple of times (scaling the images, the firmware and calculator pages). But we need to make sure we consider that side cost.
- The docs last a lot longer than forum posts. The forum posts have half lives of maybe 3-6mo, in my mind. So bringing in anything older than that risks people saying things like, “Same problem here” on a post from 2 years ago after finding a post from the docs. Maybe the fact that these are live (or nearly live) updates will make that a non issue.
Can you explain the thought process someone would take to make these useful? I’m not trying to be critical, I just hope to see their benefits the same way you do. Someone is on the docs, and they see these badges and then what?
1 Like
Cheers Jeff, appreciate the feedback and questions.
Understand and agree. Been writing script that runtime injects visual cues/links to related forum content. So, the markdown Doc content doesn’t need to be edited/modified, just need to include a script block (or script file reference) at very top of the markdown.
I’ll create a (rough) demo to help better communicate usage scenario/value…
1 Like
Considered using one of the many many Markdown’sh flowchart diagram generators like PlantUml or Mermaid ?
Have used mermaid in the past to quickly embed sequence/activity/other diagrams within markdown docs. Spent many hours faffing with Visio over the years, until these libraries turned up.
That would be cool but it is the actual content part that is hard.
I think If I just started it would be easy to fill in as it failed people. Adding it to the list.
I’m not sure a flow chart is that useful at communicating to people who aren’t used to them. Mermaid is awesome though.
But drawing it out, and then finding a way to describe it would be useful, for a couple of critical, common problems.
Just having a list of common problems and how to solve them for a particular symptom would be great. I remember @robertbu making a big post about Z slipping issues. We should find that and convert it to the docs, if you want troubleshooting there.
2 Likes
Making progress. I waited for some things to come together that have not yet so I am moving forward and will continue to tweak the sites as we go.
Currently the new “shop” theme is up, https://shop.v1engineering.com/ I have a few more fixes and pages to move and that page will be the new “home” page and I will not use the wordpress site anymore (it still serves some doc’s pictures so it is not going away yet).
I have also made a few format changes to the docs and well as added a dark theme option at the top. I hope it will automatically select the correct color scheme depending on your browser preference. https://docs.v1engineering.com/
1 Like
Oh and I looked at all the bundling options for the shop and the current version is going to be the one I stick with. I have made a couple updates but have more to go (mostly involving the LR3).
Okay, can’t seem to find an easy way around swapping the domain names.
V1EngineeringInc-Docs/version1.md at 8b264b6e64f309fe1ca136b7524d59c78eac6b2a · V1EngineeringInc/V1EngineeringInc-Docs · GitHub When I have V1Engineering.com point to the new site all the old DOCS image links are going to break.
- The easiest thing is to let them break, search and replace with whatever the new domain is. I can leave it a IP address or change it to a subdomain but that will take a while (days to propagate fully I suspect).
- some sort of offline site tool should pull all external images, right? Then maybe I can mash it together with a new pull request. Any other ideas?
3)Maybe I download them all from the old site (going to be lots of extras), add them to github, in the same file structure they are in now, then search and replace the url to the current location?
Well there are only 137, I might be able to brute force this.
1 Like
Just be mindful that the docs have an open source friendly license.