Which non V1E projects have great docs/guides that have been a joy to follow, and enabled you to be successful with your builds?
What did you like about those project docs?
Which tools do you like using for collaborative rich content editing (with versioning, approval, feedback, and other CMS features)? Ideally open source, but would be neat to know about paid features/solutions that are outstanding.
Personally like the V1 Engineering Docs, and greatly appreciate all the time and energy Ryan continually invests into expanding, and refining them.
I also love-hate github managed markdown for collaborating and creating documentation for projects like these.
Love the versioning/diff/approval-process capabilities.
But, I dislike how the Markdown syntax increases the friction/barrier of people making edits, providing feedback. Guessing the tool friction is enough that experienced technical writers hanging out here may not submit as many edits, than if tooling/process was easier.
Would be nice to use a tool that still creates Markdown, but has an intuitive WYSIWYG rich text editor that anyone that know words 'n stuff could easily use to contribute, either to create/edit content, and/or provide feedback/tips anchored to specific assembly/operation steps that are trickyā¦
fwiw - a while back I experimented with augmenting the existing github.com/ā¦/V1EngineeringInc-Docs based on MkDocs, with links to video clips for specific tricky assembly steps. Not sure how useful people would find that?
I really like markdown, and specifically mkdocs. I know there are a lot of packages that convert into pretty websites and most of them have moved to markdown. This editor is markdownish.
There are some competing formats, like ReStructured Text. But markdown is very popular.
A WYSIWYG editor would be great. I have no problem using something like the built in github editor or obsidian. But we also installed plugins for some advanced stuff that makes it render slightly different in mkdocs.
One big advantage markdown has over something like M$ Word or google docs is that the formatting is set for the whole site in one place. There is no one changing the font in a certain section or making blue text (without a lot of work).
It can also easily be rerendered in something like jekyl or readthedocs if we wanted to convert it. Markdown is the killer feature, IMO, and it enables git integration (which doesnāt have to be github, but Ryan knows it well enough).
FWIW, Ryan and I have both had great feedback that our doc system is the best and other companies have followed our methods. Especially the GitHub actions that compile and publish on any edit.
I also really like the prusa/e3d instructions. They really fall into step by step instructions. The trick would be intelligently subdividing all the instructions into different procedures so that we could effectively guide users to different steps. Something like. āGreat, youāve finished routing the stepper motor wires, continue to wiring the controllerā with links for LR4/Jackpot and LR4/SKR instructions.
Videos are excellent to give a birdās eye view of any tutorial. There isnāt any more effective way to communicate something like this. But the drawbacks are: They are very hard to update. Adding a voiceover or editing the video requires a lot of time, software, source files, and skill. They are not great to follow along with. It is much easier to skim words to find the next step than it is to skip through a video and play/pause to follow along. Atomic videos of single steps would make both of these issue go away. The third drawback is just that they are more expensive to make (in terms of energy and person-power) than text.
I think for minor edits, the current system canāt be beat. I mean it can be done from a browser and most people do not have to even think about the formatting.
It would be nice to have a wysiwyg editor to save a half a step for the giant edits, but it is not horrible to use and I am pretty confident vscode probably has a Markdown plugin to do most of the work.
I like the Prusa guides too. Specifically that people can add ācommentsā to each step - this reduces the barrier for getting feedback and information.
Most users will build a machine once only. So they may not feel confident enough to propose a change to the guide having only done it once. Or they may assume it was their own misunderstanding if a section was difficult. The number of users who would take the time to go though any process of āpull requestā or whatnot is going to be limited to longstanding users who arenāt looking with novice eyes anymore.
When I built my lowrider 4 I did not have any real problems with the instructions you already have they are clear and easy to understand. I think the problem is that people tend not to read ALL the instructions.
I have also built a Millennium Machines Milo mill and those are also very good instructions
Some sections would really need some video clips or a video clip (without audio just the same instructions caption) oh what is needed for the asembly of that part
I like the structure here and that they have the assembly manual split into separate pages that link to the next one. This is also using mkdocs.
@azab2c Is this topic for considering improvements to the V1 docs, some other project, or just general discussion?
I know for personal projects, I just use markdown within the github repo and edit it locally with a preview in vscode or with the editor on github. Iāve also thought about using the github project wiki feature but havenāt messed with that much.
At work, we use the wiki in Azure Devops. Thatās more appropriate for internal documentation though due to how accounts work.
I do think markdown is the way to go. It keeps you in a style box for consistency. Itās easy to diff changes and itās pretty simple. As a developer, I hate wysiwig editors but donāt mind markdown editors because theyāre basically just syntax shortcut toolbars. If I want wysiwig, Iām using MS Word or similar.
Make V1E docs easier for community to contribute to.
Reduce time Ryan spends related to supporting and managing questions/docs.
Creating another tool/project I never finish would be a bonus. Ideally though, thereās existing tools/extensions to support these goals.
So, am hoping topic responses will help us discover and learn about more project docs that people love. That info could help inform whether thereās some existing extensions/tools we can use to further improve the neat doc setup created by Ryan/Jeff/others.
Have been wondering if Markdown backed WYSIWYG editor would result in more contributions from the community. I partly created this topic to help feel out how true that suspicion is.
I like and write Markdown almost daily for work/pleasure. But Iām not normal, and neither are the other people that like editing large markdown documents . I use VS code extensions for markdown preview and spell checking.
Enabling Makers to easily leave feedback, comments, tips on individual steps without cluttering the existing doc content seems helpful, i.e. higher priority than optimizing editing experience?
Enabling Users to comment on individual steps would be nice. But would need to have easy way for content authors to easily āresolveā and delete comments that become stale/irrelevant as content improves. The comments would need to be a net benefit, and not time consuming to manage/moderate.
Iām familiar with various static site building tools in general along with forking and submitting pull requestsā¦but I was still hesitant to submit as proposed revisions while building my machine since I wasnāt sure how open the project is to accepting submissions.
I know some projects like to have a single person or small team manage the docs and pretty much just ignore all pull requests - while others are very open to community support and welcome them.
So - maybe some kind of documented policy on it and a link on each page of the docs to encourage people to submit issues or pull requests if they find any errors or have any suggestions.
Personally if I was managing the project I would encourage issue reports with errors and suggestions - and then prefer having someone experienced take those reports and make the updates to the docs to help keep them consistent in style and tone. That also alleviates the need for new builders to learn markdown/mkdocs to submit changes. Just encourage them to share their feedback in issues and let those who are willing to put in the extra effort make the actual updates.
I shared a few of my notes about the docs specific to the LR4 build in my build thread (where Ryan acknowledge them and that he was working on updates) but a few things Iād say about the LR4 docs overall having just built my machine:
Breaking it down into more pages would be nice, especially if the docs get bigger and more detailed. I often found myself opening to a specific step and having to wait for images to load in from other sections causing the page to shift which was really annoying.
Clicking images to view them fullsize has never worked on the docs for me - the progress indicator never goes away and the large image never loadsā¦I just have to right click and open them in a new tab to view larger versions. (Chrome on both Mac and Windows)
Iād love to see the calculator updated to give the option to work in reverse. I also had issues with getting the calculator to update on changes - the onkeyup event listener itās using doesnāt detect if you use the arrows in the input field:
So Iād make changes and then not realize they hadnāt triggered a recalculation. Iād have to shift from inch to mm to get it to recalculateā¦but that would cause the numbers to change slightly when Iād switch back. I eventually realized what was happening and started typing in numbers manuallyā¦but it drove me crazy a few times.
I actually looked at modifying the code so it could work in reverse - allow inputting table size or rail size to see how much cutting area it would give. But I saw a PR from Nov with some changes to the calculator that looked like it would address the usability issues I experienced but it hadnāt been accepted yet so I was hesitant to put time into any changes that could cause a conflict with an existing PR and wasnāt sure if that PR was going to be accepted.
Overall the Docs are pretty good - but are definitely aimed more at experienced builders and would benefit from some additional organization and more detailed photos in some places.
Oh - it may also be nice to give a warning to not use SS bolts on the tool mounts if you want to hang a z probe magnet from them Took me a few days to figure out that I had SS bolts and that was why my magnet just wouldnāt stick like the one in the photos did!
There is a pencil on each page and this section is on the front page. I donāt know how many people actually read it.
Hmm. Yeah. That makes sense. We love the forums here. But it does make sense to have a comment with a problem directly associated with the place in the docs where they got lost. That would be a paradigm shift, for sure. But the people following the āyellow brick roadā are going to be following the instructions. If we want the instructions to be the best, then maybe a comment system there would make those that much better.
We also need to get the experts here to move there to respond. I believe we would have a strong motivation to get people sorted out in the comments. And maybe a little more heavily handed on purging and editing unrelated comments over there.
Is there a hybrid system that could work? Maybe each page or major section has a link to a post in the forums?
My biggest challenge is the pictures come before the description. Iām used to writing technical documentation / workshops where I canāt rely on screenshots. I have to assume the reader canāt see the images and is accessible.
Couple years ago I was frustrated with how the Forums contains helpful info not surfaced in the static Docs. So, I experimented with marking up V1E Docs with comments backed by Forum posts that are tagged with doc section anchor references. For example User posts with #belts in a āLowRider Doc Commentsā Topic would render related comments in the matching LowRider Doc section, e.g. https://docs.v1e.com/lowrider/#belts, this could work and be good enough providing Doc sections are not frequently renamed (whichād break the link, unless aliasing/fwdān supportedā¦).
My thinking was the Forum is where people mostly already observe change notifications, and processing content/question tasks. So, would be good to have comments continue to be backed and managed by Forum topics. To manage/moderate comments, Forum Admins could just edit/deprecate Forum posts as they do today, except, they might now also remove/rename āDoc Linkā tags in Forum posts.
Created python script to crawl the forum for Doc tagged posts and generate JSON data. Then created a javascript file that gets included by mkdocs. On page load, comment edit/view features are added to each section header. I didnāt figure out a good way to support live adding/editing comments within the docs directly that wouldnāt require standing up a small service/web-app/storage for the task. Not a big deal, but I was trying to keep operating cost close to 0.
I can try and dig this out again if the idea of tying Docs and Forum content/support closer together seems interesting?
What of you have two forum posts with a link to the same paragraph? What if there are none?
It sounds close to good. I am just not sure I follow the whole implementation.
Some other design thoughts:
Ideally a plugin in mkdocs would add the code without having html or javascript added to the markeown files. IDK how those work. But it will reduce the barrier of entry to make it cleaner.
Ryan ultimately will be responsible for all of this. Many of us have been here for years. But when we get busy with our lives, he has to fix these things. Itās ok to push him a little, but it needs to be somewhat atomic or simple so he can digest it. Thereās no problem when he can add or remove a plugin.
I wonder what the appetite would be for a plugin in discourse. I donāt have the keys for the forums (for good reason) so that would be tough. But if we could automatically create a forum post based on a doc step, or at least audit which pages are missing, that could work.
The docs are a moving target (so are the forums). Keeping the information relevant when the versions change would be a challenge. A little future proofing could go a long way.
Is any of this reusable by smaller projects not related to V1? I know a lot of people like the docs and the forum solutions we found.
IDK, this sounds like a big challenge. Interesting to see your project. And there is a good system in there somewhere. I am not sure if it is worth the commitment to go through with it.
I used to like to roll my own thing but I generally avoid that now because it can be a lot of work, and then Iām the only person who fully understands it. I agree that if something can be done within the bounds of existing functionality or an existing plugin, I would lean that way. I would at least start there. I donāt think this needs to be overcomplicated (although I often find myself overcomplicating things).
I see that there are comment plugins for mkdocs, but that may lead to support chaos. I think this could be as simple as adding a doc update tag/section in the forums and create posts in there when something comes up. This can either be a person suggesting an update, or another forum member helping out by creating the post with a link to the related forum post if appropriate. If there is a person who is responsible for overseeing doc updates, this is something they could monitor and that topic could be used for clarifying/discussing what an appropriate update may be. When complete, whether thatās because the docs were updated, or it was deemed an update was not needed, the topic can be closed.
Thanks, though to be fair - I was looking for that info and didnāt find it. The pencil link (I assume youāre referring to the one with the pencil over a doc in the upper right) wonāt do anything but take you to a login page if youāre not already logged into github.
And I never realized there was a docs homepage. Even knowing it existed and looking for it just now it took me a couple of tries to figure out how to navigate there without just knowing to go do docs.v1e.com.
I was able to find the github repo since Iām used to looking for those and itās obvious up at the top. But once I was there I didnāt see any obvious contribution policy. The project homepage has a link to contributors, but no link to the contribution policy.
Perhaps just a small āThese docs are community supportedā with that link in the footer would help make it more apparent how to contribute.
This could be where you define the role of the āpaidā support/documentation person - monitor and reply to comments on the build instructions, refer users to the forum for more help and update the pages that are āhotspotsā for people getting stuck.
. I use VS code extensions for markdown preview and spell checking.
Took me a few days to figure out that I had SS bolts and that was why my magnet just wouldnāt stick like the one in the photos did!