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 <[email protected]> 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.
