Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Show HN: Instant documentation site for Github projects

documentup.com

Post reply on HN
Print view View original

11–20 of 22 posts

Re: Show HN: Instant documentation site for Github projects

#11

Post by ricardobeat »

LeafStorm wrote: post #9

One nice thing about GitHub and Bitbucket's focus on the project's README is that more software projects are providing a good, instantly-readable summary of their project in the README instead of making you have to go elsewhere to find out what it's all about and how to get started. One not-so-nice thing about GitHub and Bitbucket's focus on the project's README is that I have noticed several projects that dump all t…

I prefer all-encompassing READMEs over incomplete scattered documentation.

Re: Show HN: Instant documentation site for Github projects

#12

Post by stock_toaster »

ricardobeat wrote: post #11
LeafStorm wrote: post #9

One nice thing about GitHub and Bitbucket's focus on the project's README is that more software projects are providing a good, instantly-readable summary of their project in the README instead of making you have to go elsewhere to find out what it's all about and how to get started. One not-so-nice thing about GitHub and Bitbucket's focus on the project's README is that I have noticed several projects that dump all t…

I prefer all-encompassing READMEs over incomplete scattered documentation.

I think all-in-one-README works well for some things, but some of our projects at work would result in HUUUGE readme files. Not so pleasant if those were a single file. We have started using gollum-site[1] for our stuff that grows beyond a medium size length.

The single-long-readme length issue appears to be alleviated by the nav construction in documentup though. Pretty slick.

https://github.com/dreverri/gollum-site

Re: Show HN: Instant documentation site for Github projects

#13

Post by acdha »

If you're looking for a more mature service, particularly if you're already using Sphinx, checkout http://readthedocs.org/ which includes nice things like full text search, PDF generation, versioning, etc. and supports other hosting sites and version control systems.

Re: Show HN: Instant documentation site for Github projects

#16

Post by code_pockets »

LeafStorm wrote: post #9

One nice thing about GitHub and Bitbucket's focus on the project's README is that more software projects are providing a good, instantly-readable summary of their project in the README instead of making you have to go elsewhere to find out what it's all about and how to get started. One not-so-nice thing about GitHub and Bitbucket's focus on the project's README is that I have noticed several projects that dump all t…

Agreed, though I'm guilty as charged.

This has led me to re-think the README/documentation problem, and gave me an app idea. A little web app that allows the user to build a proper README with a template. Sort of those build a resume apps, but for README files. I plan on building it at the end of February, after I ship my current foss project.

Re: Show HN: Instant documentation site for Github projects

#17

Post by kmfrk »

Are you considering adding SmartyPants to the formatting? Then again, SmartyPants takes options for which kind of formatting you want to use, and, at least in the Python version, I never go with the default one, so it's probably useless to me without the ability to specify my specific formatting.

I really hope this gets a lot of attention; it's one of the best things I have seen on Hacker News in months, and I'm surprised we haven't even hit triple-digit karma for it.

Re: Show HN: Instant documentation site for Github projects

#20

Post by skeptical »

This adds side navigation to README's header structure. I'm sorry if I sound negative, but I don't find this of much value. As mentioned by other users, readme files are not suposed to contain a big bulk of documentation, and they already support formatting anyway. Github also offers per project wikis and sites (which this is based on). Do we really need such a tool just to generate an index? Wouldn't this make more sense as a bookmarklet for those who want it?
Post reply on HN