Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
Improve this question
I have been wondering why so many coders have bad organization in their documents.
I think I know why.
As usual it has to do with standardization. If no standard it out there, everyone has to reinvent the wheel all the time.
So I upload a gem at RubyGems.org. But that was only 1/4 of it all.
I have to write a tutorial for it, making categories, text style, size, color etc
I have to generate API documentation from my code
I have to put it in Git-hub (never done this, but that should be correct?)
It's a painful process.
Wouldn't it be great if every gem followed the same documentation structure. You upload your gem, you write a documentation for it that everyone can edit, the API documentation has been generated too, maybe created automatically, if you provided your account information for example.
A good process.
I think that would boost up good collaboration and environment than every gem has its own structure (bad documentations) and putting API documentation here and there.
Don't you agree?
Would be nice if it were more of a style like that. It's worked well for wiki's having the content changeable by the community. I've found that gem documentation can be hit or miss sometimes. I think having the documentation editable would be good because people could rewrite parts that are unclear making it much more user friendly
Great suggestion!
This kind of documentation (tutorial, non-generated doc, ...) is better addressed by a wiki.
Most of the public source container out there now integrates one in their features.
GitHub recently improves its own wiki system.
It also proposes GitHub pages (for publishing content to the web by simply pushing content to one of your GitHub hosted repositories, with user pages or project pages, and with Jekyll for even more Makdown file formats)
Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 9 years ago.
Improve this question
Basically, the title already says it all: How do I get started with Go? Of course I know the Go website and the documentation that is there, but what other resources are there?
Any good tutorials, videos, blogs, books, …?
Start with http://tour.golang.org. It will guide you through the language features and differences.
Then install it locally and try to port something simple you've written in another language.
The most important resources are the standard package docs and sites like http://godoc.org/ which provides an online documentation generator for any public code repositories.
The document Effective Go is also very useful for explanations of how to use the various language features.
There is a collection of videos on the Go wiki.
For blogs, try http://blog.golang.org/ , http://dave.cheney.net/ , http://labix.org/ and http://www.goinggo.net/ for starters.
Unfortunately, the Go books that are out there are aiming at a moving target so they struggle to be comprehensive. I'd recommend sticking with the official package docs which are usually replete with code examples.
A good tip for idiomatic code is to read the package source files, especially the *_test.go files as they usually provide nice examples of most of the ways the package can be used. This is, as an aside, a wonderful side-effect to comprehensive package tests.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
I call this a flash meeting, but maybe there is another more appropriate name.
Once in a while (and sometimes more often) one of my developers comes to my desk and asks how he should code a particular piece of code.
The code itself is not directly answering a feature, meaning that it hasn't been designed during requirements, but it is part of the feature's internal behavior.
After discussing for 5 minutes, we settle on a solution. My question is how should I record that discussion so that in the future, when someone else looks at that piece of code, that person will understand why it was developed this way and not that way?
Should I ask the developer to write directly in the code the summary of the discussion, or should I open up a Word template and write down the discussion as if it was a 2 hour meeting? Any suggestions?
This is where having a development wiki really pays off. You can just create a wiki page for the flash meeting, and link it to relevant other pages. Write up what was discussed, then ask the other programmers to check it and update as they see fit. There is one place to record everything and you can link it to whatever else you need, for instance SVN urls to a code branch or link to other wiki pages for the other people involved, the codebase being worked on. Later on, if you need to look it up, you can also search for keywords which you put into the wiki page specifically to make it easy to find later.
I'd do it with the code, as long as its not an essay. a brief paragraph and you're done.
There's nothing that would bother me more than viewing a piece of code and then having to go down to some share to look for a word document that explains it.
As long as its a small feature related discussion. big design stuff should go into its own meta document, most likely.
History information can go into version control checkin comments
In the information can be captured briefly, then one option is for the developer to describe the discussion in the comment when s/he checks the file(s) into version control. If you don't trust developers to look in source control if they have questions, then add "See checkin comments for this file on mm/dd/yy" in a comment in the source before checking it in.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 3 years ago.
Improve this question
My next project will be a lightweight PHP alternative to Trac, since Trac is often confusing to install and is often a little too big or feature-rich for smaller project.
Features planned so far:
Wiki
Bug tracker
Forum(s)
Static pages (easily edited of course)
Markdown support
No code repo hosting (I consider this a feature since most people would prefer to use a 3rd party such as GitHub for the actual code hosting)
My question: if you were to use a self-hosted app for making a website about one of your open source projects, what would you want? Is there anything on that list that's missing? Would you absolutely require the ability to actually host the code repo on the site itself, or would you be ok hosting the code elsewhere (Google Code, GitHub, BitBucket), and using the site only to upload major versions?
Summary: if you were to use a self-hosted app to provide info and support for an open source project of yours, what would you want it to be like?
Redmine is my current favorite, I usually install it via BitNami
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 8 years ago.
Improve this question
Should I just go to SourceForge and try to find something that looks interesting by doing a search? Or is there a Ruby-specific website that helps you to find open source projects to contribute to?
After you find it one, do you usually just send an email to the project owner to see if you can help or do you just start submitting code to their repository and they will take it or leave it after reviewing it for quality?
The standard hosting site for Ruby projects is RubyForge. Another site that is slightly older than RubyForge, is the Ruby Application Archive (RAA). In addition to RubyForge, there are also a lot of Ruby projects hosted on SourceForge. Projects that are specific or related to JRuby, are sometimes hosted on CodeHaus or Sun's new project hosting site Kenai. For IronRuby, some projects live on CodePlex. Projects that use the Git Version Control System, are often hosted on either Gitorious or GitHub, whereas projects that use the Darcs Version Control System tend to be self-hosted.
However, especially larger Ruby projects often have their own infrastructure, e.g. Merb, DataMapper and of course Ruby on Rails.
I'd recommend going onto github to look for projects. You can search around, check things out easily and its easier for the project owner to manager your changes.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I've read only good things about Merb, but the documentation on the website is basically the api reference, and right now there is no books already published.
Any resources about Merb?
I guess that I'll start to read the code, but it'd be nice to have another sources of information
The wonderful PeepCode have got a Merb PDF and screencast available for $9.
The source code is really readable, pretty compact and full of comments.
Then, each merb part have a complete README full of informations too.
You can read all this on github: http://github.com/wycats/merb/
I think merb has been pretty bad about good example code, tutorials and updating dated information. I really like the project, but have been stung by this several times. Now that it has reached a semi stable 1.0 I really hope that some people step up and get a bunch of the docs up to date, add warnings to old docs and point it towards newer information. It should be great to see how they deal with supporting the project now that it is 1.0
There's the Merb Wiki and also a community book project, you can see it at http://book.merbist.com/ and the source is on github: http://github.com/mattetti/merb-book/tree/master.
You are correct. As the website will tell you, Merb is a hacker's framework. Yehuda called it an experimentation ground in a recent infoq interview . There is a lack of good examples because the system has changed a lot since its inception. Dec pointed out the github pages. They are the best source of current documentation that I know of. With the release of 1.0 the API has become stable, which will hopefully lead to less broken code examples.
I can also highly recommend the #merb IRC channel on FreeNode. Friendly, smart people.