5 ms·

I like that the docs look less like they jumped out of the geocities era. Still could go a long way though. Signalling is important, and if you signal "old and

I like that the docs look less like they jumped out of the geocities era. Still could go a long way though. Signalling is important, and if you signal "old and unupdated" to your users, that's not a great start. (e.g.: http://docs.racket-lang.org/pkg/Package_Concepts.html http://docs.racket-lang.org/pkg/Package_Concepts.html) "prev", "next" (when the table of content is right there next to it) and "top" (usually the header / logo link these days) and collapsible TOC trees screams "we copied this out of MSDN '97 and windows .chm files". The "...search files..." looks like it was written by a programmer. The white on gray line with the black on white line next to it looks odd. Natural spacing sometimes is a great substitute for lines. The main docs page (http://docs.racket-lang.org/ http://docs.racket-lang.org/) contains way too many fonts and way too many colors. Pick a scheme and go with it. My favourite examples of docs that look like people cared: http://flask.pocoo.org/docs/quickstart/ http://flask.pocoo.org/docs/quickstart/ (well designed, tasteful font, color and spacing selection) http://docs.vagrantup.com/v2/getting-started/index.html http://docs.vagrantup.com/v2/getting-started/index.html (lack of search bugs me) https://developer.mozilla.org/en-US/docs/Web/CSS/:nth-child https://developer.mozilla.org/en-US/docs/Web/CSS/:nth-child ("hide sidebar" here serves a real purpose: hides the whole thing so the doc display is wider, kinda nice that TOC follows you) Conclusion: Glad it's improving, but please keep at it! Great docs make your product a joy to use! ------------------------- edit: let me add some WORSE examples to put things into perspective: https://www.tcl.tk/man/tcl8.6/TdbcCmd/tdbc.htm https://www.tcl.tk/man/tcl8.6/TdbcCmd/tdbc.htm http://junit.sourceforge.net/javadoc/ http://junit.sourceforge.net/javadoc/ (ughhhh) http://www.gnu.org/software/smalltalk/manual/ http://www.gnu.org/software/smalltalk/manual/ (whenever I see the gendocs selection page I get nostalgic. Really? 120 vs 420kb? I didn't care even when I was using dialup. Also the "one webpage per node" version almost always sucks because you can't search for anything. And the "all in one page" version sucks because it's too huge sometimes. Who uses the ascii text version or the info docs version?)

tekacs 13y ago
I think you have a valid point (other than in the case of the Vagrant docs, which I absolutely detest [0]). The simplest way to make good-looking docs might just be to 'just use Sphinx' (as does Flask, mentioned and http://docs.python.org/ http://docs.python.org/ and [many others][1]. Another example of amazing docs (they've always been pretty decent, but amazing in their most recent style) are the PHP docs: http://www.php.net/manual/en/function.pg-affected-rows.php http://www.php.net/manual/en/function.pg-affected-rows.php The docs are a necessity to make up for the shoddy, inconsistent patchwork that is their language design, but they are damned well designed and easy-to-use for the wading through flat scope that is required by those who use the language. Similarly, styles based on YARD/codo (http://coffeedoc.info/github/coffeedoc/codo/master/ http://coffeedoc.info/github/coffeedoc/codo/master/) are pretty nice for API references. [0]: Disappearing sidebar when you resize to narrow, huge amounts of spacing everywhere and sidebar names that can't be expanded without navigating to their root. :/ [1]: http://sphinx-doc.org/examples.html http://sphinx-doc.org/examples.html
- makmanalp 13y ago
  Ooooh the PHP ones are even better than they used to be, I hadn't checked in a while. I have always loved the user comments in docs idea. I've noticed so many bugs, gotchas and idiomatic patterns simply by looking at those comments. I bet it gives the devs a good idea on what to work on next, too. It didn't used to have votes which was bad because it perpetuated bad advice sometimes, but now it seems they have that too!
userbinator 13y ago
> http://junit.sourceforge.net/javadoc/ http://junit.sourceforge.net/javadoc/ (ughhhh) Despite me not really liking Java all that much, the javadocs can be very useful; although in that example they chose a bad non-default colour - black on (dark) green is difficult to read. Here's a better example, they normally look more like this: http://www.jdom.org/docs/apidocs/ http://www.jdom.org/docs/apidocs/
taeric 13y ago
I disagree with your examples. Taste is an odd thing that way. Specifically, previous/next are great if you are reading it straight through. I agree this isn't that likely, but is nice to have. (I have actually used these. Recently, even.) The fonts and colors are mostly pleasant. I can see how you would like other schemes. But I can't find anything atrocious. I love how linked everything is. Specifically in the code samples. Even in the intro[1], all code samples are linked to the docs for what is there. Contrast this with the flask documentation, where if I want to see what @app.route does, I have to go find it elsewhere. So, yes. There are things I would find to complain about if asked to look for them. At no point in actually perusing and using the site have these ever bothered me. And there are more niceties thrown in there that have made things easier than any of the complaints you mentioned. [1] http://docs.racket-lang.org/guide/intro.html http://docs.racket-lang.org/guide/intro.html
brudgers 13y ago
When Racketeers talk about documentation, they're not talking about the sort of documentation that you are holding out as better. They're not talking CSS and markup and formatting. No. When Racketeers talk about documentation, they are speaking in Lisp and the context is code as data and data as code. When Racketeers talk about documentation they are talking about Scribble. http://docs.racket-lang.org/scribble/index.html http://docs.racket-lang.org/scribble/index.html Scribble is Racket's documentation tool. It adds an independent documentation phase to the Lisp expansion. Here is Mathew Flatt introducing it: http://vimeo.com/6630691 http://vimeo.com/6630691 None of the examples even comes close. The closest thing is EMACS Org.mode, but it is still ad hoc to whatever language one is documenting.
- makmanalp 13y ago
  My critique was more on the visual side of things. I think it matters. That said, onto your comment: I liked the presentation. The @ notation is kinda neat and elegant, and no doubt enabled by the ridiculous power macros give you in terms of modifying how everything is parsed. It's cool that it's implemented as a DrScheme lang, and it can run and is all code-is-data-y, and it's not a totally separate language. However, I don't really see anything in here that any modern document processor (say http://sphinx-doc.org/ http://sphinx-doc.org/) can't perform. The second-last question brings up a great point that when you tightly couple your documentation language with the platform (PLT), you run the risk of it being a PITA to use it to document other languages. I think the presenter's solution of automatically creating stub classes and such is really unsatisfactory and kinda kills the benefits. So there you have it, there are pluses and minuses. I think Scribble is neat, but it's really not all that out of the ordinary.. It's definitely not true that "nothing comes close".
  - brudgers 13y ago
    Beware the Blub Paradox. http://www.paulgraham.com/avg.html http://www.paulgraham.com/avg.html
    - makmanalp 13y ago
samth 13y ago
I think we just disagree on taste for documentation pages. For example, I find the Vagrant docs somewhat garish and hard to read. The current look of the Racket documentation was designed by Matthew Butterick. You can see his excellent book on typography and design here: http://practicaltypography.com/ http://practicaltypography.com/ -- and it was made with Scribble, the same system that generates Racket's documentation.

tekacs 13y ago

I think you have a valid point (other than in the case of the Vagrant docs, which I absolutely detest [0]). The simplest way to make good-looking docs might just be to 'just use Sphinx' (as does Flask, mentioned and http://docs.python.org/ http://docs.python.org/ and [many others][1]. Another example of amazing docs (they've always been pretty decent, but amazing in their most recent style) are the PHP docs: http://www.php.net/manual/en/function.pg-affected-rows.php http://www.php.net/manual/en/function.pg-affected-rows.php The docs are a necessity to make up for the shoddy, inconsistent patchwork that is their language design, but they are damned well designed and easy-to-use for the wading through flat scope that is required by those who use the language. Similarly, styles based on YARD/codo (http://coffeedoc.info/github/coffeedoc/codo/master/ http://coffeedoc.info/github/coffeedoc/codo/master/) are pretty nice for API references. [0]: Disappearing sidebar when you resize to narrow, huge amounts of spacing everywhere and sidebar names that can't be expanded without navigating to their root. :/ [1]: http://sphinx-doc.org/examples.html http://sphinx-doc.org/examples.html

makmanalp 13y ago
Ooooh the PHP ones are even better than they used to be, I hadn't checked in a while. I have always loved the user comments in docs idea. I've noticed so many bugs, gotchas and idiomatic patterns simply by looking at those comments. I bet it gives the devs a good idea on what to work on next, too. It didn't used to have votes which was bad because it perpetuated bad advice sometimes, but now it seems they have that too!

userbinator 13y ago

> http://junit.sourceforge.net/javadoc/ http://junit.sourceforge.net/javadoc/ (ughhhh) Despite me not really liking Java all that much, the javadocs can be very useful; although in that example they chose a bad non-default colour - black on (dark) green is difficult to read. Here's a better example, they normally look more like this: http://www.jdom.org/docs/apidocs/ http://www.jdom.org/docs/apidocs/

taeric 13y ago

I disagree with your examples. Taste is an odd thing that way. Specifically, previous/next are great if you are reading it straight through. I agree this isn't that likely, but is nice to have. (I have actually used these. Recently, even.) The fonts and colors are mostly pleasant. I can see how you would like other schemes. But I can't find anything atrocious. I love how linked everything is. Specifically in the code samples. Even in the intro[1], all code samples are linked to the docs for what is there. Contrast this with the flask documentation, where if I want to see what @app.route does, I have to go find it elsewhere. So, yes. There are things I would find to complain about if asked to look for them. At no point in actually perusing and using the site have these ever bothered me. And there are more niceties thrown in there that have made things easier than any of the complaints you mentioned. [1] http://docs.racket-lang.org/guide/intro.html http://docs.racket-lang.org/guide/intro.html

brudgers 13y ago

When Racketeers talk about documentation, they're not talking about the sort of documentation that you are holding out as better. They're not talking CSS and markup and formatting. No. When Racketeers talk about documentation, they are speaking in Lisp and the context is code as data and data as code. When Racketeers talk about documentation they are talking about Scribble. http://docs.racket-lang.org/scribble/index.html http://docs.racket-lang.org/scribble/index.html Scribble is Racket's documentation tool. It adds an independent documentation phase to the Lisp expansion. Here is Mathew Flatt introducing it: http://vimeo.com/6630691 http://vimeo.com/6630691 None of the examples even comes close. The closest thing is EMACS Org.mode, but it is still ad hoc to whatever language one is documenting.

makmanalp 13y ago
My critique was more on the visual side of things. I think it matters. That said, onto your comment: I liked the presentation. The @ notation is kinda neat and elegant, and no doubt enabled by the ridiculous power macros give you in terms of modifying how everything is parsed. It's cool that it's implemented as a DrScheme lang, and it can run and is all code-is-data-y, and it's not a totally separate language. However, I don't really see anything in here that any modern document processor (say http://sphinx-doc.org/ http://sphinx-doc.org/) can't perform. The second-last question brings up a great point that when you tightly couple your documentation language with the platform (PLT), you run the risk of it being a PITA to use it to document other languages. I think the presenter's solution of automatically creating stub classes and such is really unsatisfactory and kinda kills the benefits. So there you have it, there are pluses and minuses. I think Scribble is neat, but it's really not all that out of the ordinary.. It's definitely not true that "nothing comes close".
- brudgers 13y ago
  Beware the Blub Paradox. http://www.paulgraham.com/avg.html http://www.paulgraham.com/avg.html
  - makmanalp 13y ago

samth 13y ago

I think we just disagree on taste for documentation pages. For example, I find the Vagrant docs somewhat garish and hard to read. The current look of the Racket documentation was designed by Matthew Butterick. You can see his excellent book on typography and design here: http://practicaltypography.com/ http://practicaltypography.com/ -- and it was made with Scribble, the same system that generates Racket's documentation.