Thanks for the feedback Kristoffer. Glad you’ve found the package useful!
Re: assuming certain knowledge. I think that for a very new package such as this it’s definitely alright to make a fair number of assumptions. Going forward I’ll be looking to expand those bits that have, until now, been glossed over and start to make things more beginner-friendly, to a certain extent. — Mike On Sunday, 19 June 2016 01:00:00 UTC+2, Kristoffer Carlsson wrote: > > My view is that the README was perfectly fine. What do people think that > the image that says [docs - stable] is there for if not for clicking and > being taking to the docs..? They also share the same form as all the other > badges which are clickable to go to the coverage, testing status etc. > > I have used Documenter in a few of my packages and it was really simple to > set up the whole thing since the documentation explains everything so > clearly. There are also multiple other packages that uses Documenter that > are linked from the documentation so you can just go and look how they did > stuff if there are still questions. Also, this package is for users who are > developing packages so assuming a decent amount of knowledge of general > Julia stuff is in my view fair game. > > Just wanted to add my feedback so that multiple inputs are heard. > > > > On Sunday, June 19, 2016 at 12:01:54 AM UTC+2, Michael Hatherly wrote: >> >> It honestly did not cross my mind that those pictures were links. >> >> To me they shout click me, but I *really* do understand the issue you’re >> highlighting Daniel. I’m busy updating the page to add some real links. >> Thank you for pointing it out, much appreciated! I think we can safely >> wrap up that part of the conversation. >> >> Blaming the user all the time is not going to lead to good documentation. >> I am giving you user feedback. >> >> That’s not my intention, apologies if that came across that way. I’ve >> simply >> written the docs for the package with a set of assumptions in my mind >> about >> what knowledge is already available elsewhere. I’ll definitely make use >> of your >> feedback and improve/clarify the parts the need it. Thank you. >> >> 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. >> >> I’ll be adding a link to the relevant docs in the Julia manual. The >> markdown parser >> has been part of Base since 0.4 was released and is mentioned in the >> Documentation >> <http://docs.julialang.org/en/release-0.4/manual/documentation/> >> section of the manual. If things could be clearer in that section then >> please open >> an issue or PR so that that can be fixed. >> >> It SHOULD teach the basics of Markdown. >> >> I believe that we are probably just going to disagree one this one. A >> link to >> the relevant information is fine for something like this. I wouldn’t >> expect >> every single thing that I read to begin from first principles. That’s >> just how >> I prefer to read things, though that’s probably just a personal thing. >> I’d be >> fine with a PR to add a basic syntax tutorial if you’d like. >> >> what flavour of Markdown >> >> That’s discussed in the main Julia docs >> <http://docs.julialang.org/en/release-0.4/manual/documentation/>. >> ------------------------------ >> >> If I’ve still not addressed things enough, could a ask you to open some >> issues >> in the Documenter.jl repo please? A long email thread is the best place >> for >> these kind of important issues to get lost in and never get resolved >> properly. >> Even if it’s just a couple of one-liner issues that would make fixing >> these >> much easier for me. Thanks. >> >> Once again, thank you for taking the time to discuss this. I know your >> time, >> just like my own, is limited and could be being spent on other things. >> >> — Mike >> >> >> >> On Saturday, 18 June 2016 22:56:45 UTC+2, Daniel Carrera wrote: >>> >>> >>> >>> On 18 June 2016 at 18:34, Michael Hatherly <michael...@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. >>> >>>
