53 pointsby emschwartza day ago6 comments
  • thevinter23 minutes ago
    I like the interactivity, some of the ideas are nice and I do agree that it's nice when docs are something more than giant walls of text. However...

    I think mixing docs and user data is fundamentally a UX mistake. Having interactive components that showcase a behaviour is nice, having them actually toggle some settings less so. Permanently altering the state of the application discourages experimentation, and many users might not even realise that the changes are permanent.

    Additionally, a documentation should be designed as to reduce as much external noise as possible, allowing the reader to focus on the things that actually matter. I feel like introducing real-world data can end up being too distracting.

    Personally I don't feel like your application warrants a documentation (and don't get me wrong, I'm the first that spends hours overengineering stuff) and I guess that the interactive stuff makes it feel even less so. If I haven't known beforehand I would've guessed the pages to be just another (slightly busy) section of the app. (and whether that's good is for you to decide)

  • dfajgljsldkjag3 hours ago
    I really like that you used the live code components inside the documentation pages. The biggest problem we have in this industry is that the manual becomes wrong as soon as we update the software. If the documentation runs on the same code as the app then it will never be out of date. This is the only reliable way to keep the instructions accurate over time.
  • stephenlf4 hours ago
    I love this approach. Great work. Building helpful, accurate has been the second hardest part of building my employer’s internal app. (The most difficult thing has been reaching consensus on processes.)
  • whatever14 hours ago
    Just copy what Mozilla did for MDN.
  • gregory1447 hours ago
    This is like building a custom swagger implementation
  • emschwartz6 hours ago
    Developer here, happy to answer any questions you might have about Scour!

    Also, feedback on the product or the docs is very welcome!