Some ideas for this awesome project :)
fgrehm opened this issue · comments
Hey @progrium,
First of all, thanks for this awesome project! I really like the idea and I think it makes up for a pretty awesome alternative to github pages for documentation! The fact that you don't need to manage a separate branch neither you need to resort to things like Jekyll or Middleman to have something more "advanced" (like layouts) has hit me pretty hard :)
So I was wondering how it could be improved and I came up with a few things that I'd like to know your thoughts before attempting my first ever Golang pull request :P
JSON metadata
This is related to the rest of the stuff described below and it is about having some sort of metadata bundled with the project. Maybe some viewdocs.json on the project root that gives viewdocs some insights about the project when building it.
"Tagged docs"
Well... you know.... things changes and a new feature might have been introduced on a version that also has a breaking change that prevents people from upgrading. If we keep displaying only the docs from the master branch it might end up getting some people into trouble.
My idea was to leverage GitHub's release api and build docs for specific versions. Something like http://<github-username>.viewdocs.io/<repository-name>/<version> and use latest as the version for the current master or we could require users to list all versions on the JSON manifest file in order to make things less "magical".
README fallback:
GitHub has the automatic page generator and for smaller projects I think a README is enough. So my idea was to have a fallback to rendering the README in case the docs folder is not found. There's still the issue of specifying a pre made layout and a Google Analytics tracking code but this information could also be kept on the JSON manifest :)
I'm not really sure if it would be possible to somehow automatically grab the pre made github templates but I'm fine with marking that "out of scope" :P
CHANGELOG.md support
I'm not 100% sold on this one yet but apart from the README fallback we might also have support for rendering changelogs in a nice looking page. I'm also fine with not having this feature, just wanted to know your thougts on it as it is something that has crossed my mind.
I hope you like the ideas or that at least it gives you some food for thought :)
Great ideas. Let me tell you my thoughts.
JSON metadata
Interesting idea. I'd be willing to go this direction when there are more
reasons to introduce the complexity. (I quite like how simple it is now)
"Tagged docs"
I was thinking of building that into the URL as well. Though without
configuration. /repo would always go to master, and /repo~branch would take
you to a branch or tag. I imagined the default layout having links to other
versions be pulled automatically, a la readthedocs ... however it would be
easy enough for projects to do this themselves with custom layouts. It
would be simpler and just as effective.
README fallback:
I'm torn about this one. If you just have a README, isn't the Github
project page good enough? Having another URL with the exact same
information seems to just make more unnecessary links for a project.
CHANGELOG.md support
Github already renders md files, so linking directly to the CHANGELOG.md
file seems like a Good Enough solution to me.
JSON metadata
Interesting idea. I'd be willing to go this direction when there are more
reasons to introduce the complexity. (I quite like how simple it is now)
yeah, if we leave the other stuff out of the table there's no reason to keep that.
At least it's a "somewhat simple" solution to support additional data if for whatever reason the project ends up getting more features. Either way, that made some ideas unrelated to this project pop in my head that I hope I'll be able to implement at some point :)
"Tagged docs"
I was thinking of building that into the URL as well. Though without
configuration. /repo would always go to master, and /repo~branch would take
you to a branch or tag.
Yeah, that makes sense, we can just error out or throw a 404 in case the tag can't be found, there's no need to use the API 👍
README fallback:
I'm torn about this one. If you just have a README, isn't the Github
project page good enough? Having another URL with the exact same
information seems to just make more unnecessary links for a project.
It usually is enough but I thought it would be a nice alternative to the github automatic pages generator which by default loads the content from the README and requires manual intervention in case of updates. Yeah, it is an additional link but I've seen quite a few projects that uses that (which unfortunally I can't seem to find now) and this is likely to make people lives easier as the website would always stay up to date.......
.....but.... after a second thought I think it actually makes sense to leave this "out of scope". It would end up encouraging people to keep those looooong and boring readmes around 👍
I'm not sure you have anything to add to the discussion, so feel free to close this issue in case you dont :)
So I guess if you want to add the branch/tag support, that would be really
great. :)
On Mon, Nov 11, 2013 at 12:55 PM, Fabio Rehm notifications@github.comwrote:
JSON metadata
Interesting idea. I'd be willing to go this direction when there are more
reasons to introduce the complexity. (I quite like how simple it is now)yeah, if we leave the other stuff out of the table there's no reason to
keep that.
At least it's a "somewhat simple" solution to support additional data if
for whatever reason the project ends up getting more features. Either way,
that made some ideas unrelated to this project pop in my head that I hope
I'll be able to implement at some point :)"Tagged docs"
I was thinking of building that into the URL as well. Though without
configuration. /repo would always go to master, and /repo~branch would take
you to a branch or tag.Yeah, that makes sense, we can just error out or throw a 404 in case the
tag can't be found, there's no need to use the API [image: 👍]README fallback:
I'm torn about this one. If you just have a README, isn't the Github
project page good enough? Having another URL with the exact same
information seems to just make more unnecessary links for a project.It usually is enough but I thought it would be a nice alternative to the
github automatic pages generator which by default loads the content from
the README and requires manual intervention in case of updates. Yeah, it is
an additional link but I've seen quite a few projects that uses that (which
unfortunally I can't seem to find now) and this is likely to make people
lives easier as the website would always stay up to date............but.... after a second thought I think it actually makes sense to
leave this "out of scope". It would end up encouraging people to keep thoselooooong and boring readmes around [image: 👍]
I'm not sure you have anything to add to the discussion, so feel free to
close this issue in case you dont :)—
Reply to this email directly or view it on GitHubhttps://github.com//issues/1#issuecomment-28237857
.
Jeff Lindsay
http://progrium.com
Sure! I'll see if it can fit in a tomato later on tonight :P