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