Documentation best practice
-
We would like to improve our documentation experience for new users. Does anybody have some examples of other projects that have good documentation for new users we could use as best practice?
-
I think your documentation is pretty good myself.
-
Overall I agree the documentation is quite good. What might be good in addition to what you have would be walkthrough guides to the initial setup for each type of printer, so rather than having to hunt down each section to get examples of how to configure hot end, fans, probes etc. there could be one document that takes you through the process. A bit like reprap pro used to do for their online build documentation.
I appreciate the downside is there will be a duplicate of information.
-
What might be good in addition to what you have would be walkthrough guides to the initial setup for each type of printer, so rather than having to hunt down each section to get examples of how to configure hot end, fans, probes etc. there could be one document that takes you through the process.
This is the plan! What we're hoping to solicit in the meantime is examples of guides and documentation that other users have found to be useful. That way we can nail down the best ratio of words to photos, the right level of detail, etc.
-
My twopence worth….......
When I built my RepRapPro Mendel, starting as a complete newbie, I found their documentation to be really good. The commissioning docs are here. https://reprappro.com/documentation/commissioning-introduction/calibration-duet/ I'd guess though that you guys might have had a input so you are probably very familiar with them already.
It's nicely broken down into sections which makes things easy to find, but I think what makes the difference is lots of screen shots and pictures. It is often a lot easier to grasp the meaning of something as an image, rather than converting text to a "mental image" which is what many of us do, even if it's subconsciously. So I'd say that whenever possible, use a screen shot or picture to supplement the words.
Just don't "do an Ikea" and use only pictures with no words at all
-
One thing that might be useful is to clearly separate the "getting started" parts from the "technical documentation" parts.
In one section, there could be a set of guides written towards users who have not yet got their controller working. These would have lots of photos, have more plainly worded instructions, and with the goal of safely getting the printer running.
Then, in another section, there could be a more technically-oriented set of documents that just lay out in detail the functionality of everything.
By separating the two sections, with the goals of both sections being vague but clear ("inform new users" vs. "rigorously document features"), it might be easier to write and maintain the documentation.
-
I like the style of the prusa guides for building the printers
Especially usefull is the possibility to leave comments in case something is not clear
-
Prusa made everything perfect.
-
I hadn't seen Prusa's docs before, but I see they Dozuki, as does SeeMeCNC. A nice feature of that system is the user can click to generate a PDF, for local reference.
-
Wow… also the ability to comment on individual steps. Whatever that is, I'm sold.
-
@AS-3D:
Prusa made everything perfect.
Agreed - their manuals are very good. Also, the ability to comment on sections was very helpful to me when I built my MK2. Some good hints from users that had gone before. Also, the ability to easily see larger version of the photos is very helpful too.
-
I think your documentation is great but I came to Duet like probably the majority of users with experience in 3D printing. It does seem this user group doesn't really struggle but certainly some beginners would find a lot of it very confusing.
I like the idea of having each guide separated into Quick Start/Basics and then the full in-depth explanation that we currently have.
-
I was going to suggest Prusa as a good example too.
But I also think the current Documentation and Wiki is very good
Setting up from scratch was fairly easy (After a previous ramps build, so like DjDemonD I'm not a complete NOOB)
The only time I've slipped up is after making changes thanks to firmware updates (Eg Dual Z leveling) I didn't go back and read the manual (So even the best documentation wouldn't have helped me!)Oh & Duet Documentation is a million times better than Smoothieware
-
I recommend treating it as a living document, constantly attended to and updated when required as things change. There are few things worse than a static document with known deficiencies or errors that are never updated and cause needless headaches for all future users.
In general, I do not find that to be the case with Duet's documentation; but there is room for improvement in the WIKI. I have found that I cannot even find something I just stumbled across previously. And I finally just bookmarked the page with supported G-Code out of frustration with trying to figure out how I got there the last time. I don't know, maybe I am missing something like an accurate index or site map.
-
I recommend treating it as a living document, constantly attended to and updated when required as things change. There are few things worse than a static document with known deficiencies or errors that are never updated and cause needless headaches for all future users.
In general, I do not find that to be the case with Duet's documentation; but there is room for improvement in the WIKI. I have found that I cannot even find something I just stumbled across previously. And I finally just bookmarked the page with supported G-Code out of frustration with trying to figure out how I got there the last time. I don't know, maybe I am missing something like an accurate index or site map.
I agree, navigability of the current system is the only area that really needs improvement.
-
A good step by step guide with lots of pictures would be a huge help for first time users. It should be more newbie orientated.
Maybe one for Cartesian, one for Delta and one for CoreXY? I mean example builds.The wiki is great, the information is extremely detailed and I really thank the devs for constantly updating it. But to be honest, in some occasions, it feels overwhelming. Many of us don’t like to tweak with the software, we just want to print, make, build and do all sorts of mechanical stuff, so when it is firmware related we feel lost.
And take in consideration that a lot of people with 3d printers may know a lot of 3d printing but know nothing about compiling a firmware. The Rostock Max for example: You assemble the printer, then upload the pre-configured firmware and you are good to go. You only need to mess with the firmware if you change something. I'm sure there are a lot of other printers that follow this same situation.
In my particular case, it passed more than a year before I decided to buy a Duet, and it was not because of a money issue. It was because I couldn't figure out how to replace the Rambo and use the Duet. There was too much information on the Wiki and I couldn't understand it. I felt stupid because, if I had to ask in the forum, I didn't even know what to ask. All these new concepts were very confusing to me. Until I read mhackneys DuetWifi conversion guide (http://www.sublimelayers.com/2016/12/converting-seemecnc-rostock-max-v3-to.html), that made me pull the trigger.
So, thank you Michael, this is by far the best upgrade done to the printer.Sorry for my English, it's hard to express myself in another language.
Keep up the good work, I love my Duet.
Martin -
@bot:
Wow… also the ability to comment on individual steps. Whatever that is, I'm sold.
I was just going to suggest exactly that - great to know there's already a solution. The ability to easily give feedback as you're following directions should very quickly highlight what areas need what improvements.
