I'm redoing our docs right now. My experience tells me devs want 2 things, an evaluation tool and howto, howto best via chatbot, evaluation text (security, architecture, basics of getting going) via a regular old webpage, does this track with what people here want? am I thinking about this correctly? Thank you for helping me with my homework! :)
Howto is super important to me, it's absolutely bananas how many docs seem to assume you understand the whole library and don't explain any surrounding context or how things effect other things in the context.
Especially bad in 100% documention requirement shops where you get stupid things like '@param foo - Control <foo>' where having some examples would be much more useful than a wall of those parameter 'descriptions'.
Is a chatbot kinda annoying then? Chat bot with a bit of a guide better? I presume you open docs ctrl F and search for whatever? Would you be annoyed trying to "search" with a chatbot? Tnx btw.
Our chatbot isn't trying to answer questions as much as it is to point people in the right direction.
People have made chats that are better at actually solving problems but the usecase we targetted was I have a question how do I get to the answer. This works better than search, because it allows for semantics to work, for example when someone asks about SvelteKit, even though our docs don't mention it, the ai points towards the Vite docs.
Yes, yours feels very good! I apologize, I was hijacking your post a bit, sorry for it. I happened to be working on a docs revamp project this week so it seemed like a good place to ask my questions, I've been trying to think how robust to build the chat function of the docs/onboarding etc. as it seems things are going in this direction, but I'm still cognizent of the fact that docs are as much an evaluation of a product as they are how to use the product. Anyway, sorry again for using your HN post for my homework. :)
Hi, I'm working on something tackling this problem. Do you mind if I contact you for more discussions?
feel free, email in bio.
I definitely prefer it to to be text.
I'm not a fan of chat bots on random websites, but also my work is pretty regulated so as far as AIs go we're only supposed to use ones we have direct agreements with.
While I can just not put in anything protected I much prefer being able to point one of the bots we can use at docs and be able to provide it context for what I'm working on.
From my experience with my canvas library, devs seem to want different types of documentation for different purposes:
1. Something that tells them what the library does: what problems it's gonna solve for them; how easy it is to work with; etc. Having something to play with is really useful here, for instance some "Getting started" code to (very quickly) show them the basics and let them play with the library. A set of "learn to" lessons tackling some interesting problems is good bonus documentation, alongside a good range of demo code.
2. Something that they can show to whoever controls which libraries they can use in the product they're working on, to help convince them to let the dev use the library. Usually involves some marketing copy and comparison charts - whatever A/B tested copy|crap floats the boat.
3. Some easy-to-use lookup reference stuff - what function do I have to invoke to get this specific thing done? Stuff that their coding environment doesn't reveal at the click of a button. This is where the LLM-focussed documentation comes in (I think), given the move to using code assistants: failing to (be able to) teach the models what the library can do (and how to best do it) can lead to bad code and wasted time, which reflects really badly on the library.
Thanks for this, I really appreciate you taking the time!