badgers and non-badgers
:D In fact, I like the setup: all the badges along the top and prose afterwards. Yes, that’s a good compromise. Happy to make a change like that. — Mike On Saturday, 18 June 2016 21:54:03 UTC+2, Mauro wrote: > > As others in this thread, I was confused by (and thus ignored) those > documentation badges the first time I saw them, even though I was using > the travis badges regularly. To help badges-challenged people like > myself, maybe add a normal link too? In fact, I like the setup: all the > badges along the top and prose afterwards. This serves both the badgers > and non-badgers. (I agree though that you can keep the readme short if > other docs are provided.) > > PS: Thanks, Mike, for all your work on the Julia documentation system! > It has come along nicely and a very long way since you started working > on it. > > On Sat, 2016-06-18 at 18:34, Michael Hatherly <michael...@gmail.com > <javascript:>> 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. > > > > without a link in the README > > > > There are links in the README. > > > > 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. 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 :) > > > > I saw that line too. > > > > I GUESSED that maybe Markdown > > > > 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. > > > > use markdown syntax inside docstrings > > > > That is covered by the main Julia manual. 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. > > > > 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. > > > > I think it’s great that now there is a documentation package for Julia > and > > I’m very glad you wrote one. So thank you for that. If I get the time, I > > will make a PR. > > > > Thanks, and I’d also like to thank you for all your input on the > docsystem > > discussions in #3988 and elsewhere. > > > > — Mike > > > > > > On Saturday, 18 June 2016 17:30:54 UTC+2, Daniel Carrera wrote: > >> > >> Hi Mike, > >> > >> Thanks for being cool about my (hopefully constructive) criticism. I'm > >> very glad that there is now a package for documenting Julia code, and I > >> expect to use it in the future. So thanks for that. > >> > >> > >> On 18 June 2016 at 15:20, Michael Hatherly <michael...@gmail.com > >> <javascript:>> wrote: > >> > >>> It has two lines on installation, one line on project status, and two > >>> sentences on “contributing and questions”. > >>> > >>> You’ve missed out the section called “Documentation” there. Perhaps > you’re > >>> viewing a cached version of the README that isn’t showing it for some > >>> reason. > >>> > >> > >> The "Documentation" section has literally one sentence (one I don't > really > >> understand). Here is the entire section from the raw file: > >> > >> -------------------------- > >> > >> # Documentation > >> > >> Documentation is built automatically with help from *MkDocs* on *Travis > CI* and hosted by *GitHub Pages*. > >> > >> [![][docs-latest-img]][docs-latest-url] > [![][docs-stable-img]][docs-stable-url] > >> > >> ## Project Status > >> > >> -------------------------- > >> > >> > >> > >>> the README file of a documentation package should have at least as > much > >>> documentation as the README files of other non-documentation Julia > packages > >>> > >>> Adding additional duplicated documentation to the README when there is > >>> already > >>> a substantial amount of documentation elsewhere isn’t really worth > doing > >>> in my > >>> view > >>> > >> Well, the point of a README file so to have useful information about > the > >> package. The current file is close to empty (but maybe I'm looking at > an > >> old version?). Also, how are people going to find documentation without > a > >> link in the README? Lastly, it is standard for Julia packages to have a > >> short introduction and documentation in the README. This file is also > often > >> used as a gateway to the rest of the documentation. For example: > >> > >> > >> https://github.com/plotly/Plotly.jl > >> https://github.com/stevengj/PyCall.jl > >> https://github.com/JuliaLang/ODE.jl > >> https://github.com/staticfloat/Opus.jl > >> > >> > >> Notice that PyCall has a very extensive README. But even a very short > >> README like the one from Opus.jl still includes sample code, and some > >> information about usage. I would call Opus.jl an example of a poorly > >> documented module, and the author still thought it was a good idea to > >> explain a bit about how the package works and what it does. In > contrast, > >> with Documentation.jl the only way I know to find information is to go > to > >> my email client and find this thread. > >> > >> you should state what markup language you are using. > >>> > >>> That is mentioned directly above the feature list in the summary line: > >>> > >>> A package for building documentation from docstrings and markdown > files. > >>> > >>> so I didn’t feel the need to duplicate that again in the feature list. > >>> > >> > >> It is not duplication, it is clarity. I saw that line too. This is > partly > >> why I GUESSED that maybe Markdown is used. That, and the file that > Julia > >> docs often use Markdown; but I only know that because I've been around > >> Julia for a while. The one sentence you are referring to does not in > any > >> way say or imply that you can use markdown syntax inside docstrings. I > >> mean... cant you actually use Markdown inside docstrings? I suspect you > >> can, but I don't actually know for sure. I know that in your email you > >> basically said "yes". But how much of Markdown do you support? Which > >> flavor? I think that these are things I should have been able to infer > >> easily since this is the core feature of your package (unless I > >> misunderstood the package). > >> > >> There is such a thing as too much duplication, but you are nowhere near > >> having that problem. Currently the documentation is closer to the > opposite > >> end, where you tend to write the bare minimum and it seems like you > expect > >> users to try to guess what you might have been thinking. That's not > where > >> you want to be. I would also argue that it's better to err on the side > of > >> being "too clear", rather than not clear enough. > >> > >> > >> > >> > >>> Maybe add some examples showing the use of Markdown. > >>> > >>> There’s already a number of examples that illustrate the syntax in the > >>> “Guide” > >>> page and “Syntax” page. > >>> > >> > >> I did scan at the Syntax page. On a second look, I do see examples of > >> Markdown. If I didn't already know some Markdown, I think I would have > >> missed it on the second look as well. The thrust of this section seems > to > >> be about @doc, @autodocs, and the other blocks in the package. I didn't > >> imagine that the examples were supposed to introduce some bits of > Markdown > >> syntax. > >> > >> > >> > >>> PRs to improve the docs are most welcome since it’s always difficult > to > >>> read > >>> the docs from the point-of-view of a new user. Thanks for taking the > time > >>> to > >>> have a look at the package Daniel. > >>> > >> > >> I think it's great that now there is a documentation package for Julia > and > >> I'm very glad you wrote one. So thank you for that. If I get the time, > I > >> will make a PR. > >> > >> Cheers, > >> Daniel. > >> >
