I don’t want to be rude
No worries, I’m not taking your criticism at rudeness. 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. Not sure why that would be, but there definitely is a section between “Installation” and “Project Status” linking directly to the docs. Could you post a screenshot of what the README look like to you? 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 — especially when the complete docs are a single click away. Note that there is an open issue <https://github.com/JuliaDocs/Documenter.jl/issues/12> for automatically generating the README from files in docs/src, which would go some way to resolve the duplication problem. 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. 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. 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. — Mike On Saturday, 18 June 2016 14:17:44 UTC+2, Daniel Carrera wrote: > > No there aren't. I am looking at the README right now. It is nearly blank. > It has two lines on installation, one line on project status, and two > sentences on "contributing and questions". The second of those sentences > has a link to the issues page. > > I don't want to be rude, but the README file of a documentation package > should have at least as much documentation as the README files of other > non-documentation Julia packages. It is normal in Julia packages to have > documentation in the README, often including a link to more detailed > documentation in readthedocs.org or similar. > > > One bit of constructive criticism for the documentation: in the features > list, you should state what markup language you are using. Is it Markdown? > Probably, but that's something that should be stated explicitly. Maybe add > some examples showing the use of Markdown. > > Cheers, > Daniel. > > > On 18 June 2016 at 12:26, Michael Hatherly <michael...@gmail.com > <javascript:>> wrote: > >> There's two links in the README (the blue "docs" badges), one in the repo >> header, and one in the second paragraph of the first post of this thread :) >> >> -- Mike >> >> On Saturday, 18 June 2016 11:49:04 UTC+2, Daniel Carrera wrote: >>> >>> I can't find any documentation for this module. How does it work? How do >>> you use it? What mark up language does it use? etc etc. The README file is >>> basically blank, and the docs directory doesn't seem to contain any actual >>> docs. >>> >>> Daniel. >>> >>> >>> On Friday, 17 June 2016 11:07:26 UTC+2, Michael Hatherly wrote: >>>> >>>> I’m please to announce the initial release of Documenter.jl >>>> <https://github.com/JuliaDocs/Documenter.jl> — a documentation >>>> generator for Julia. >>>> >>>> The package docs are here >>>> <https://juliadocs.github.io/Documenter.jl/stable>. >>>> >>>> The package is still a work-in-progress, but now has sufficient >>>> features to make a stable release worth while. Major breaking changes >>>> should hopefully be few and far between from now on. >>>> >>>> If you have already been making use of the package, which quite a few >>>> of the community have been, then I’d would like to extend my thanks to you >>>> for helping file bug reports, feature requests, and pull requests. >>>> >>>> Please do upgrade your .travis.yml configuration to reflect the fact >>>> that Documenter is now tagged and available from METADATA. All that >>>> should be needed is to replace either >>>> >>>> Pkg.clone("https://github.com/MichaelHatherly/Documenter.jl";) >>>> >>>> or, more recently, >>>> >>>> Pkg.clone("https://github.com/JuliaDocs/Documenter.jl";) >>>> >>>> with >>>> >>>> Pkg.add("Documenter") >>>> >>>> and your build scripts should work fine. Any problems you happen to run >>>> into should, as always, be reported on the GitHub issue tracker >>>> <https://github.com/JuliaDocs/Documenter.jl/issues>. master will be >>>> more unstable from this point on. >>>> >>>> If you do have a publicly available package that is making use of >>>> Documenter, then please do add a link to the Examples >>>> <https://juliadocs.github.io/Documenter.jl/stable/man/examples/> page >>>> if you’d like. >>>> >>>> Finally: I’d like to thank one of our Google Summer of Code students, >>>> Morten Piibeleht, who is developing some great new features for the >>>> package >>>> over the summer. >>>> >>>> — Mike >>>> >>>> >>>> >>>> >
