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. >> >>
