Moving wiki/documentation to Github?
Ariya Hidayat
may get more exposure just because Github is quite prominent these
days. I am not married to Google Code wiki, so I am quite open to that
idea.
If you guys have some experience and/or notes about Github wiki, feel
free to share it with us! Other feedback and comments are also
appreciated.
Thank you!
Best regards,
--
Ariya Hidayat, http://ariya.ofilabs.com
Nicolas Perriault
> If you guys have some experience and/or notes about Github wiki, feel
> free to share it with us! Other feedback and comments are also
> appreciated.
IMHO the docs should be versioned in the phantomjs repository itself,
using sphinx & rst or similar… then you could host the docs on
http://readthedocs.org/
In my own experience github wiki's not that nice, making links and
generating TOC is quite painful, no search, etc.
Just my two cents
++
--
Nicolas Perriault
https://nicolas.perriault.net/ — http://www.akei.com/
Skype: nperriault
Phone: +33 (0) 660 92 08 67
Ivan De Marino
That would make it part of the dev process.
The only issue I have, is that I find a bit "annoying" that the doc is in place A, issues are in place B and source is in place C.
Makes me feel... messy.
We are doing a decent job at keeping stuff linked together, but I'd love to have everything in 1 place.
But that's just me...
Jon Leighton
GitHub wikis are actually backed by a git repo. So you can edit in your
editor and do all the normal git operations on it if you like.
The advantage of using the wiki rather than putting documentation in the
source tree is that you can give people access to edit the wiki without
giving them commit rights on the project.
In terms of the format, I really like Markdown.
Finally I'll go out on a limb and say that I prefer GitHub over Google
Code for basically everything, so I'd be happy if the issues were moved
there too...
On 30/03/12 12:11, Ivan De Marino wrote:
> I'd love the idea to have the docs in a "/docs" subdir and have it with
> the source.
>
> That would make it part of the dev process.
>
> The only issue I have, is that I find a bit "annoying" that the doc is
> in place A, issues are in place B and source is in place C.
> Makes me feel... messy.
>
> We are doing a decent job at keeping stuff linked together, but I'd love
> to have everything in 1 place.
> But that's just me...
>
> On 30 March 2012 07:46, Nicolas Perriault <nperr...@gmail.com
> <mailto:nperr...@gmail.com>> wrote:
>
> On Fri, Mar 30, 2012 at 08:25, Ariya Hidayat
> <ariya....@gmail.com <mailto:ariya....@gmail.com>> wrote:
>
> > If you guys have some experience and/or notes about Github wiki, feel
> > free to share it with us! Other feedback and comments are also
> > appreciated.
>
> IMHO the docs should be versioned in the phantomjs repository itself,
> using sphinx & rst or similar� then you could host the docs on
> http://readthedocs.org/
>
> In my own experience github wiki's not that nice, making links and
> generating TOC is quite painful, no search, etc.
>
> Just my two cents
>
> ++
>
> --
> Nicolas Perriault
> https://nicolas.perriault.net/ � http://www.akei.com/
> Skype: nperriault
> Phone: +33 (0) 660 92 08 67 <tel:%2B33%20%280%29%20660%2092%2008%2067>
>
>
>
>
> --
> *Ivan De Marino*
> Coder, Technologist, Cook, Italian
>
> blog.ivandemarino.me <http://blog.ivandemarino.me> |
> www.linkedin.com/in/ivandemarino
> <http://www.linkedin.com/in/ivandemarino> | twitter.com/detronizator
> <http://twitter.com/detronizator>
Ariya Hidayat
> IMHO the docs should be versioned in the phantomjs repository itself,
> using sphinx & rst or similar… then you could host the docs on
> http://readthedocs.org/
>
> In my own experience github wiki's not that nice, making links and
> generating TOC is quite painful, no search, etc.
Thanks for the info, Nicolas!
The lack of search will be a serious showstopper here. If I look back and see the questions/issues I've tackled, some of them are a matter of looking up the right wiki page to pull the info. And if there is no way to search the docs, I'm sure the rate of such questions will just increase because people can't find the stuff.
Is there a workaround for this wiki searchability problem? I'm sure it's possible to build/reuse existing indexing mechanism and hook it to a search box in phantomjs.org, but such additional effort defeats the original intention of keeping the maintenance as minimal as possible.
Regards,
Ariya Hidayat
> place A, issues are in place B and source is in place C.
> Makes me feel... messy.
>
> We are doing a decent job at keeping stuff linked together, but I'd love to
> have everything in 1 place.
> But that's just me...
Let's tackle one problem at a time :)
Ariya Hidayat
> editor and do all the normal git operations on it if you like.
For the record, wiki in Google Code is also backed by a repository.
> The advantage of using the wiki rather than putting documentation in the
> source tree is that you can give people access to edit the wiki without
> giving them commit rights on the project.
True. OTOH I don't believe it's too much hassle for using the pull
request workflow to add/modify/edit the documentation text.
> In terms of the format, I really like Markdown.
Agree!
> Finally I'll go out on a limb and say that I prefer GitHub over Google Code
> for basically everything, so I'd be happy if the issues were moved there
> too...
Few things I'd like with Google Code which Github does not have yet
(or I can't find how to use it):
* Issue voting via the 'star' mechanism. That gives an overview of the
impact of a particular issue.
* Matrix dashboard, like in http://issues.phantomjs.org.
* You won't be notified (or spammed) forever just because you comment
on an issue.
I'll follow Github issue tracker closely and see if over the time
losing the above features will not become too painful anymore.
Regards,
Jon Leighton
>> Finally I'll go out on a limb and say that I prefer GitHub over Google Code
>> for basically everything, so I'd be happy if the issues were moved there
>> too...
>
> Few things I'd like with Google Code which Github does not have yet
> (or I can't find how to use it):
>
> * Issue voting via the 'star' mechanism. That gives an overview of the
> impact of a particular issue.
> * Matrix dashboard, like in http://issues.phantomjs.org.
> * You won't be notified (or spammed) forever just because you comment
> on an issue.
>
> I'll follow Github issue tracker closely and see if over the time
> losing the above features will not become too painful anymore.
To be honest I would be surprised if they add any of these features, as
I doubt they'd want to complicate the UI / implementation.
Making a comment saying "+1" is what people tend to do to "vote" on GH.
You can achieve similar functionality to the matrix dashboard (though
not the same UI) through milestones/labels. And issues can be
unsubscribed from (although you are right that by default a commenter
gets subscribed - though I think that's what most people want; by
commenting you're expressing an interest in the issue).
It's a shame that there isn't a wiki search feature on the website.
Though it is obvious possible to search the git repo using normal git tools.
Cheers
James Greene
- http://trentm.com/2012/03/google-code-to-github.html (scroll to the "Issues" section... no nearby ID to link to)
This guy describes attempting a full transplantation of issues from GC to GH as "a fool's errand", and rightly so. Instead, his approach was to create a "shadow issue" on GitHub for each existing Google Code issue which basically includes a link to the Google Code issue. - The rest created other tools that offer various levels of support (e.g. some consolidate comments, some don't, etc.):
Ariya Hidayat
> but I do think that PhantomJS would benefit greatly from moving to GitHub
> Issues over Google Code Issues. Google Code Issues don't even allow us to
> post source code snippets in our issues without mucking it all up, for
> pete's sake....
attach a file or link to Pastebin/Gist.
> Obviously, being wholly consolidated on GitHub instead of Google Code would
> also be ideal, so the Wiki would probably move eventually.
therefore does not increase the discoverability of our wealth of
information). Another alternative will be to make it available as
normal HTML, part of the web site (which is already using GitHub Pages
anyway). The contents will be indexed by Google and we can always
place a custom search.
> Any which way, I did a little research on migrating Google Code Issues to
> GitHub Issues. Given the somewhat divergent set of features, it is
> impossible to do a perfect/complete transplantation. For example, it
> is generally not possible to wholesale migrate Google user's alerts to
> GitHub alerts (unless they happen to have the same user name/email, etc.).
issues. In fact, most of the issues need triaging, most of them are
old, not reproduceable, or don't have reduced test cases. We can
always move high-priority issues, i.e. things which are more important
for the upcoming releases.
As I wrote earlier, the voting system and matrix dashboard are two
main things I really like from Google Code. I am still playing and
getting myself familiarized with the much simpler label/tag approach
of GitHub and as soon as I feel comfortable then I have no problem
moving over.
Note that I'm not adamant of still using Google Code, I'm just selfish
and won't like to do all the dirty work by myself. That is, if someone
volunteers to migrate the issues and to continue to help
triaging/tagging the future issues, then that might just accelerate
the process :)
Thanks!
Regards,
http://twitter.com/ariyahidayat
Bryan Bishop
> I believe we need to have a complete 1:1 match if we want to move the
> issues. In fact, most of the issues need triaging, most of them are
> old, not reproduceable, or don't have reduced test cases. We can
> always move high-priority issues, i.e. things which are more important
> for the upcoming releases.
moves for importing issues/tickets. In this case, I am sure they would
be happy to help with the ticket dump in this case, if that's what the
decision comes to (shoot them an email asking wazzup).
- Bryan
http://heybryan.org/
1 512 203 0507
Ariya Hidayat
> issues.
1:1 match.
Ariya Hidayat
> therefore does not increase the discoverability of our wealth of
> information).
indexed and found by Google easily. For example, searching for
"twitter bootstrap roadmap" will lead to the right wiki page in
Twitter GitHub. Even Yahoo finds it, although DuckDuckGo and Bing do
not produce an accurate result (maybe they will improve over the
time).
I think it's worth an attempt to move the docs to GitHub after this
1.6 release. After that, we would consider moving the issues as well.
Any objections?
Of course, volunteers will be warmly welcomed :)
Thank you!