On 18 June 2016 at 18:34, Michael Hatherly <michaelhathe...@gmail.com> wrote:
> Here is the entire section from the raw file > > “Raw file” is the key here: those are image links below the sentence. Look > at > the rendered version on the GitHub repo rather and you’ll be able to see > the > docs badges correctly. That’s the most common way people will be browsing > for > packages. I can try make those more obvious/informative in their raw form > though. > Of course I began with the rendered file on the browser. It honestly did not cross my mind that those pictures were links. My eyes just moved past them like background noise every time I looked at this page. Please don't use buttons or icons to serve the purpose of links. Really. These are basic usability standards. If you meant to have a link, use a link. Please, trust me on that. > without a link in the README > > There are links in the README. > It took a conversation with you over several emails for me to "find" those links. This really isn't good. I'm sorry, but it isn't. I doubt that I will be the only person who will not interpret those little pictures as links that I'm supposed to click on to get the documentation. And really, what do those pictures really say? They say "docs|stable" and "docs|latest". How the heck is that supposed to mean "click here"? It sounds like you are labelling the present README (the one I'm looking at) as the stable and the latest. Those pictures look like badges. > it is standard for Julia packages to have a short introduction and > documentation in the README. > > I’m aware of what some packages chose to do. I have chosen to provide very > clear links to the documentation instead. > Your "very clear links" were missed by me multiple times, and were missed by Mauro, and I swear that I would have continued to miss them if you had not told me in this email that those pictures are links. They do not loo like links. These are *NOT* very clear links. They really really are not. I just did a test. I gave my laptop to my wife and asked her to find the documentation. She said "good question, I have no idea". Then I pointed at the little pictures and said "would you believe that those are links that take you to the documentation?" and she said "no, I would not have guessed that". So there are at least three people in the universe that did not think that you had clear links. That means that there are probably more, and the links aren't as clear as you imagine. > I would say that part of the reason > that packages make use of the README for their documentation is that there > have not been many other viable options. To me a README should provide more > developer-orientated details of a project, that’s just my view though :) > Julia is a programming languages. We are all developers. The nature of GitHub is that when you go to the GitHub page of a project you see an HTML rendering of the README file. This makes the README file the effecting *front* *page* for the project, and every project that uses GitHub should treat it as such. The README is literally the first thing that your users are going to see about your project. This isn't even a Julia thing, it's a Github thing. I just searched for Python projects on Github and look: https://github.com/donnemartin/awesome-aws https://github.com/nbrochu/requests-respectful Try other Github projects. The README is just the front page in Github and you have to accept that that is how Github uses the README file. If you saw that line then “guessed” can’t really be the right word. > I’ll add a more clear point in the introduction though. > "Guessed" is exactly the right word. And the guess was based partly on my previous knowledge that Markdown is often used in Julia. The line *does* *not* say that you can have Markdown inside docstrings. You are expecting people to imagine stuff. Blaming the user all the time is not going to lead to good documentation. I am giving you user feedback. > use markdown syntax inside docstrings > > That is covered by the main Julia manual. > How so? How is that even possible? Are you telling me that Julia comes with a built-in Markdown processor? If that is the case, that is really news to me, and it makes me wonder what your module is contributing then. I thought you were providing a Markdown processor. And if you are not, doesn't that show that your documentation has failed at conveying what your module provides? > A link could be provided to that, but > generally the route potential users should be taking is to read the Julia > manual first and then go looking for packages that they need. > This is bad documentation design. And I have been reading Julia documentation for years. I have never heard of Julia having a built-in Markdown processor. > If I didn’t already know some Markdown > > Yes, a link could be provided to resources that teach markdown. I’d be fine > with that, but Documenter’s manual is not the place to teach markdown > syntax > from scratch. > It SHOULD teach the basics of Markdown. It should not teach *all* of Markdown, but if Markdown is at the core of what it does then it definitely needs to talk about it. If I was doing this, I would have a short section titled Markdown where I say that this module implements XYZ flavour of Markdown, show an example text (a heading, a sub-heading, a couple of lists, bold, italic, underlined -- just the basics) and then say "if you want to learn more about XYZ Markdown, to go this page". I notice that in your email you still have not told me what flavour of Markdown you have implemented (or is it in Julia?). Is this also something that I am supposed to have inferred somehow? Cheers, Daniel.
