Writing FAQ articles

According to the FAQ Intro page, Hammer maintains the FAQ articles, but his account hasn't been active since '07. As a matter of fact, apart from one article two years ago, there hasn't been a FAQ article written in over 6 years. Who handles this now?

There were a few things last week that hit me as topics that should have a FAQ entry (stuff I've answered several times since I've been here). So I started working on a few FAQ articles over the weekend, and was wondering what to do with them. Numbers 2 and 3 are the ones I thought needed to be written, then I found number 1 on the "to do" list:

1. Working with multiple source files (from the old "to do" list)
2. Explanation of extern and static
3. How to compile and use a shared library (Linux/gcc)

Is there much interest out there in adding to the FAQ (AndrewHunter, I'm looking at you: http://cboard.cprogramming.com/c-pro...ml#post1048558)? If anybody has any other, ideas for FAQ articles, perhaps you could post them or even start writing them.

I suppose the same goes for the tutorial section

Good question! If you're interested in writing FAQ entries (or tutorials, or anything else) that's fantastic, and I can help you get them posted. It would be great to get new FAQ entries added.

The best way to submit FAQ entries (or tutorials or articles) is just to send them to me via email: [email protected]

I'll read them, make suggestions and edits, and take care of posting.

I think that it is just as important to update the FAQ (and other) articles, but that would be quite a mammoth task.

Quote:

---

Originally Posted by anduril462

Is there much interest out there in adding to the FAQ (AndrewHunter, I'm looking at you: http://cboard.cprogramming.com/c-pro...ml#post1048558)? If anybody has any other, ideas for FAQ articles, perhaps you could post them or even start writing them.

I suppose the same goes for the tutorial section

---

haha...good point. Luckily I do have some time to start working on these ideas, however if we are going to start this (and I do think it is a good idea) I think we should coordinate efforts so that we do not duplicate work and thus waste time.

I agree with you anduril462, I think some of these items need to be completed and others could be refined. So, I would say we should start with the FAQ "to do" list as you mentioned and then move on to a facelift of the FAQs and tutorials. We should use this thread as a prelim signup sheet of who is interested in this task and what they are willing to do / areas of expertise.

I am willing to work on an areas and I do have the time to do it; additionally I do have a deep background with corporate training if no one else wants to organize the effort.

The to-do list is actually pretty out of date.

Quote:

---

Originally Posted by FAQ To-do

Explanations of...
Using multiple source files (C)
Structures
Link Lists
Binary Trees
Recursion

---

Covered by Prelude, in her corner.
Covered by elad.

At least, covered to a large extent by elad. I think it would be wiser to incorporate the C bits missing from that article rather than starting completely over. Using project headers and source in either C++ or C is actually not that different. It's a matter of what content belongs in there. I also think that the extern and extern "C" explanations could be covered there.

Quote:

---

Originally Posted by FAQ To-do

Compiler specific
Setting up Borland 5.5

---

Really?

Quote:

---

Originally Posted by FAQ To-do

A list of useful macros

---

BUFSIZ
M_PI
NULL
The ones in <errno.h>
The ones in <limits.h>
...uh ...
assert();

Yeah.

Though it is not covered in the To-Do list(..and very few existing..(I found only one on this site) ),
I think I could write something about setting up Development Environments in Linux...i.e. how to set up IDE `s to point to the correct libraries (and in some cases compilers!), how to install downloaded libraries, how to set up the IDEs to use gdb without problems....
and a few general ones like using gdb(No, the man page isn't a good teacher at first.. :P)..and a front-end (I just noticed one tutorial explaining the basics of gdb from the terminal, here), using version control ...etc

These are the topics I've trouble finding information when trying out from the first time, so I'd rather someone else not go through some of the trial & errors involved !

Quote:

---

a few general ones like using gdb(No, the man page isn't a good teacher at first.. :P )

---

I wonder how heavily we'll borrow from this? RMS's gdb Tutorial

Quote:

---

Originally Posted by whiteflags

I wonder how heavily we'll borrow from this? RMS's gdb Tutorial

---

... Just posting a link of that would be great ! ...

Though the writing terminology maybe a bit difficult to grasp for those who heard the word debugger for the first time.

I thought that this was written by 'The' RMS until I found a link in the site saying that is is Ryan (Michael) Schmidt.

@laserlight: It is a big undertaking, but I think it's a "many hands make light work" situation, and I don't really care whether we finish in 5 days or 5 months. I think if we can wrangle up 5 or 10 competent people, and they could all give even 10 minutes a day, it wont be that bad.

@Whiteflags: I'm all for combining related things and not duplicating work. Honestly, I spent about 45 total on the 3 things I wrote, so I don't care if we toss out the multiple files bit, and hack up the extern stuff.

Regarding GDB, we actually have a tutorial covering GDB, but to me it didn't seem that noob friendly. RMS's tutorial seems better, but something even simpler might be good too.

I agree that the FAQ "to do" list is completely out of date, and many of the topics listed in it are already covered either in the FAQ itself or elsewhere on the site.

If you want to know if there's already something on the site covering a topic--ask me. I wrote most of it (outside the FAQ), so I know what's there :)

Regarding updating existing articles: unlike new articles, you should tell me in advance if you're interested in making changes or edits to existing content.

Quote:

---

Originally Posted by webmaster

Regarding updating existing articles: unlike new articles, you should tell me in advance if you're interested in making changes or edits to existing content.

---

I wrote a 3 page beginner friendly tutorial on the basics of gdb.[Edit: It got a bit longer due to the example]
Is it to be considered a new article or an alternate chapter of the existing one ?

Attached here, is the odt file(change the extension back from txt).

Attachment 10814

(I don't generally use word processors, but owing to my rather poor knowledge of markup languages, I thought it'd be better to let Libre handle it now.)


Please review...(Also, do suggest a better sort of example...mine is almost too silly!)

Just throwing in a little suggestion here...
Ideally the FAQ should go to the main page when finished, but in the mean time, we do have the cpwiki where you can edit, discuss, comment and generally just have fun and mess around. There are also a couple of articles there that might be useful merging or moving to the main site.
Once the articles there are finished, they could easily be moved to the main page.
But on the wiki, you have the advantages of editing and creating in advance and also revision history and discussing things on their appropriate pages instead of merged into a single topic.

Also, the URL: cpwiki has a problem
Just in case you want to use it, you have to create a sourceforge account if you don't have it. And finally, before being able to edit anything on the wiki, you need the appropriate privileges. To get them, you'll have to PM Cornedbee, dwks, me or zacs7. That's just how the wiki works unfortunately.

Quote:

---

Originally Posted by Elysia

Just throwing in a little suggestion here...
Ideally the FAQ should go to the main page when finished,

---

It already is. There is a link to the FAQ on every page of cprogramming.com.

I'm not sure we're speaking the same "language" here. What I meant is that all the material written (FAQs, etc) should appear on the FAQ page on cprogramming.com when finished. Not stored in cpwiki or any other place.

Oh, and for anyone wanting to edit/create articles in cpwiki, you must first login to cpwiki with your OpenID/SF account. After that, PM one of the aforementioned to be able to edit/create pages.

@manasij749: Thanks, I took a look at your article and it's a good start! I sent you a PM with suggestions for follow-up--please take a look.

Attached are two of the FAQs I wrote. I'm leaving out the multiple files, as whiteflags suggested, and I'm quite alright with parts or all of the extern/static one being merged in with another FAQ if deemed appropriate.

I'm a little confused on the purpose of the cpwiki thing. I mean, looks like it's a wiki to cover common issues here (basically a wiki FAQ), but it's not easily found when looking around this site. I can get an account and get my articles up over there too if everybody wants.

@anduril462: In your Shared Library file, would it be a good idea to introduce ldconfig instead of messing with the environment paths ?

I thought about it, and came to the conclusion that changing LD_LIBRARY_PATH is more versatile. Students who are working on school systems may not have permissions to modify /usr/lib or any of the /etc/ld.so.conf files. I think you're right however. It would be good to cover it for personal systems, for which the programmer has admin rights, and I can cover stuff like "scan the current dir" or "use my personal ld.so.conf" for people who don't have admin rights. Time to get started on v2.

Quote:

---

Originally Posted by anduril462

I'm a little confused on the purpose of the cpwiki thing. I mean, looks like it's a wiki to cover common issues here (basically a wiki FAQ), but it's not easily found when looking around this site. I can get an account and get my articles up over there too if everybody wants.

---

cpwiki was just originally intended as a place to put articles, especially common issues since people grow tired of repeating them. Back then, we couldn't get them on the main site, I believe.
Regardless, the fact that we can now put articles on the main site deprecates cpwiki. The articles there should really be ported to the main site.
However, it's still good for writing, editing and discussing articles before porting them to the main site.

@anduril462 These are very good write-ups! I think the static vs extern should be a stand-alone FAQ entry. I will edit the header file FAQ entry to demonstrate example uses of extern and static with a link to this entry, once it's posted. As for shared libraries article, I'm a bit torn as to whether it's a better fit for the FAQ or a standalone article.

I'd like to take this time to also switch the software used for the FAQ; it produces ugly looking URLs and isn't that flexible. It should be possible to have links from the FAQ to articles that appear elsewhere on the site, for situations where there are very in-depth answers to questions and it doesn't make sense to write another FAQ entry on the same topic. That might be the most appropriate thing to do for the shared libraries tutorial. I do think introducing ldconfig makes it a better fit as a standalone article.

@Elysia Let me take a look at what's on the cpwiki and see what would make sense to transfer to the main site, and where it should go. Some things are better as FAQ entries (usually shorter articles that answer a specific question--ex: static vs extern) and some things are better as full articles/tutorials (usually longer/more in-depth writeups, like the GDB tutorial which has an extensive example).

Quote:

---

Originally Posted by webmaster

@Elysia Let me take a look at what's on the cpwiki and see what would make sense to transfer to the main site, and where it should go. Some things are better as FAQ entries (usually shorter articles that answer a specific question--ex: static vs extern) and some things are better as full articles/tutorials (usually longer/more in-depth writeups, like the GDB tutorial which has an extensive example).

---

Absolutely.
And note that there are some articles that are duplicates of those on the main site which may need to be merged or simply disposed. Pause console is one that comes to mind, I believe.