With the occurrence of more-or-less the same topic within three days (here and here), of course getting similar answers, I believe that it would be useful to have a subcategory of Usage for frequently occurring topics, where people can post some lite documentation on those topics (preferably in wiki form). It would be a quality time-saving read (easier than either a Git thread or going through the various occurrences in Discourse), also a good read for new users after finishing reading the manual, and it could possibly make it into a future version of the manual itself (or it could be the other way, the manual finding its home in Discourse).
These things are already documented 20 times. There’s the manual, the wikis, the tutorials, the blog posts, the SO documentation, etc. But almost every issue new users have is in here:
http://docs.julialang.org/en/release-0.5/manual/performance-tips/
I don’t think that by posting another way new users will finally read it. I think that’s why there’s a basic usage section: hopefully new users will post their “in REPL benchmarks” there, so that way whoever has the time can help them understand this.
Also I think this kind of introduction is always much better handled using chatrooms. It’s extended and tailored to the questions you have. No general written documentation will ever match someone specifically answering your questions.
Do you have any statistics for that claim? Or is it just your personal experience when you were a new user yourself? Most issues are not performance related. The issue I mentioned above is a good example.
If chatrooms were anywhere close to an unmatched solution (I won’t bother listing their drawbacks here), there wouldn’t be any documentation in first place and the Usage category would be a dead place. Again the issue I mentioned above is a real-world refutation of that argument. Documentation is irreplaceable. The fact is that the majority of Julia users don’t visit the chatrooms in first place, many visit SO, but Discourse will gradually become the number one destination for everything Julia.
That’s not only inaccurate and exaggerating but is actually part of the problem. Multiple partial documentation (often outdated and inaccurate) actually makes things harder for users. The proposed wiki nature of the posts can fix that. Not all users feel like going through long pages of scattered information mixed with low-level stuff, when their questions look simple in their eyes. Providing users with quality up-to-date documentation is much better than giving them multiple ways to relieve their frustration.
Some will not read it. The users who initiated the threads I mentioned above (@davide and @jkroso) would have definitely read it. I even bet that the proposed subcategory will get tones of views and challenge the popularity of other categories views-wise.
It may be a good idea to have a FAQ category/subcategory, but there’s been a lot of activity and changes here to keep up with lately. Let’s rest on this and see how things feel in a while.
Also, again, please watch the contentious tone that some of these interactions are taking on.
2 Likes
I merely made a proposal here, not a demand with a deadline. If the FAQ was there, I would create some documentation myself, not urging others to do so for the sake of the proposal. I can certainly rest, however the forecast is for increasing activity, cause Julia is on the course to skyrocket, and your personal work has been one of the key reasons for that (highly appreciated). But as the community grows, so do its needs, calling for more persons to serve them and better tools to help them. Discourse is a feature-rich tool and its successful adoption can be a milestone in that journey.
I don’t like that kind of interaction and I’ve no intention to provoke it. I prefer dealing with well supported arguments, so as to learn from them. But I’m not sure if I can do more at this point, other than ignoring the need to defend my ideas, which is difficult when it occurs in topics initiated by myself. In any case, I apologize for being part of the tension.
I am expecting a fair amount of initial question that are repeating themselves coming from new users. That was my original thinking behind the First Steps category.
My main concern right now is moving julia-users, and then seeing how the usage of Discourse grows organically.
A FAQ category might be most helpful in a wiki style, but I am not to sue how that would work out.
@akis if you would like give it a try and write some posts about how to use or Julia, please feel free to do so. Posts them in Usage and I will add a faq tag to them.
@akis if you have issues with me please just PM me so it doesn’t fill the forum. That said, I prepared a line-by-line response giving you all of the sources you demanded. Let’s just bury the hatchet and be done with it. I hope this post also just serves as a good source of information to the community as well.
Indeed. I also think it would be good to take some time with what we have and add things as when we feel they are necessary. Though I think another short-term goal should be to move related forums (julia-opt, Juno’s Discourse, etc.) here as well.
Thanks for the offer, but I’m already done with it, I won’t spend more time, including arguing in the shadows. According to the FAQ (that of Discourse):
ask yourself how you would feel if your post was featured on the front page of the New York Times
If the proposal gets materialized in the future, time will ultimately prove whether it was wise or redundant.
Back to the thread’s subject,
The First Steps category (which hasn’t attracted anyone to the day of this post) states installation and performance issues. The former is definitely a first step, but the latter not necessarily so. And repeating questions are not strictly the initial ones. Any question which is not easily discoverable may potentially repeat, especially when people notice a behavior which they don’t know how to express it in a few words, so they just post some REPL session. The session’s code is probably unique, their issue probably not. What happens next? That answers the “question” below:
Other users (thinking in “healing mode”) may give a “quick” answer, one to satisfy the specific REPL situation (often opting to “skip” the issue altogether, suggesting a different approach). But a contributor (thinking in “prevention mode”) should ask: “What kind of documentation could help its readers to avoid that situation?” and then proceed to write a wiki post on the matter, probably utilizing information from the thread, but no more focusing on the REPL, focusing instead on the users’ needs (and potentially covering a whole group of similar issues, some of them not asked yet in the forum).
The tag solution cannot achieve the desired effect (for various reasons), but it’s a fair offer for demonstration purposes. Thanks, @vchuravy.
For me a FAQ category would need to have the first post of the topic to be the explanation (e.g. wiki-style posts) and the follow up to be a discussion about the finer details.
The tag is more for the purpose that once we have a critical post of FAQ topics we can easily move them into on category. In general I will advise using a tag before creating a category from now on.
1 Like
Demo entry posted here.