GHOP #94: Compile FAQ from factoids

This looks good to me. Thanks for providing all of the information to evaluate this up front. Go ahead and make a Google task for this (instructions at http://groups.drupal.org/node/7360#tasks)

Thanks

Changing title and metadata to reflect status

subscribe.

Hello,

I'm the student volunteering for this task. I'm completely loving it, up until now :)
I want to know where can I have a "sandbox" type page where I can test changes, and see how the page looks in "production"?

Thanks !

Probably the best thing to do would be to install a test Drupal site and use the book module on your test site. The Drupal handbook pages use the core Book module that ships with Drupal. If for some reason you're not able to create a test site, let us know and maybe we can come up with another solution.

Oh actually I found an easier way, even if it is a bit hack-ish. I clicked on "Create content", "Book Page", pasted the code, and clicked on preview. But I think your idea is better - of setting up a test site..

Hello,

I am attaching first draft of the FAQ. Please review it and tell me if any additional
questions are required :)

The formatting should mainly be correct, the major work left now is categorizing.
Can you please suggest what all categories are appropriate for this FAQ ?

I hope the work is to your satisfaction.
Thanks !

PS: Please don't open the html file in a browser, it will look horrible, because no
line breaks are added between questions :)

It would help to make this easier to review if you added line breaks between questions. Was there a reason you didn't add them yet?

aclight, line break tags were not added because when the code is pasted in a book in drupal, line breaks are added automatically.
Please tell me if I must edit the file and add the br tags, but it is unnecessary work imo :)

marking for review.

overall i like it, it is going to be very useful. my only problem is with the non-semantic markings. <b> should not be used to mark the questions, because its a styling element only.

Also if you want to emphasize something use the appropriate descriptive tag: <em>, not <b>, or <i>. An anchor would be most useful for each of the FAQ items, and a list of links for an overview.

Thank you snufkin - I've edited all <b> to <strong> and <i> to <em> .. I'm the process of editing the links, as aclight told.
An anchor will be added in the end, once I sort and categorize the questions.
Any suggestions on how do i separate the questions from the answers ?

Thank you very much for the praise Keith :)
I just made the DT DL DD thing consistent, and I will be modifying the document to make the links more readable and clean, as aclight suggested.

Oh, and in the next document I submit for review I'll add the IRC-related questions too :)

Here is a 2nd draft which incorporates the suggestions of aclight, keith, and snufkin. Thank you all of you !

Things left to do :
- Categorize the questions
- Sort them
- Give appropriate anchors to each question

Please give me a few guidelines on how to proceed with that :)
Also, even though this HTML page should render considerably well in any browser, it was formatted with Drupal Book in mind, so please paste the code in a Drupal test site. Refer the FAQ to learn how to create one ;) (Sorry, could not resist that !)

Thank you Keith, for the fine-comb review .. All the mistakes have been corrected (I hope).
I am submitting one more draft of the FAQ, this time with skeleton page anchors.
What I need to know is:
- Any more questions needed ?
- Are the categories enough ?
- Is the page anchoring system that I've set up for categories good enough ?
- Is it OK to have a list of all questions, and below that, a list of all answers ?
- In the anchor for each question, what is the proper a name = "..." ? A number, or a small one-word description of the question itself ?

ATM, the code is not worth pasting in a Drupal book, because it does not support HTML comments :)

In my opinion the categories you've created look good and I think the number of questions is reasonable.

As far as the page anchoring system goes, it's easier and preferred (I think) to add the id attribute to the <h3> tag itself instead of creating a separate <a name=""> tag.

So, for example, your new code might look like this:

<DT><h3 id="gettingstarted">Getting Started</h3></a>

</DT>

<DT><h3 id="customization">Customization</h3></a>
</DT>

As for how to display everything, I would suggest following the organization used at http://www.copyright.gov/help/faq/ with one exception. Instead of having the actual questions and answers on separate pages, just place your questions and answers at the bottom of the page under the list of categories and questions. If you look at the source of the link above you'll see that for each question they gave it a 1 word or 2 words separated by an underscore name to use as the named anchor, and I think that works well.

I would also like to see you rewrite the answers where you say something like "to get more information click here." to be more descriptive so that the link can be a description of what you are linking to instead of "here".

Overall this is coming together nicely and looking good. Keep up the great work.

Looking very groovy. Only a bit more proofreading to go. It's a good idea to get IDs into the headings - makes linking that much easier.
Adding a self-link (like 'permalinks') # so people can copy & paste the anchor would just be totally sweet.

<dt><h3 id="gettingstarted">Getting Started</h3><a href="#gettingstarted">#</a></dt>

or similar.

Y'know, you'd think with a decent CMS there would be a way to do this boring stuff automatically ;-)

Ok, submitting one more review copy. I have sorted and linked all the questions - I will organize the answers only after I get a go-ahead :)
So, please tell me
- if all the required questions are covered
- if any question category needs to be changed
- if any type of sorting - questions or category - needs to changed

After that, things left will be
- sort and organize the answers
- rewrite the "click here" type of links

If I have missed anything in the list above, let me know ..

Wow, that renaming of categories makes the FAQ much more readable :)
I'm reattaching the one with changes you suggested Keith, and I've removed the miscellaneous section.
Let me know if anything further needs to be done for sorting within the categories ..

Just to re-iterate, things still left to be done are -
- sort and organize the answers
- rewrite the "click here" type of links

Moving to the Documentation issue queue to get their eyes on this.

Keith, I'll correct that error in the next revision I upload.
Also, one request - I have an exam coming up on Thursday, so starting now, I will pause my work on the FAQ for a few hours. I don't think I'll miss the deadline because of this, but if I do, I hope you understand :)
Thanks !
It will actually be good, that way I can get maximum suggestions from the Documentation team too.

One query, though - how do I format the answers ? I can use

<DL>
<DT><H3 id="about">About Drupal</H3></DT>
           <DL> 
           <DT>Q1</DT>
           <DD>A1</DD>
           <DT>Q2</DT>
                   ...
           </DL>
<DT><H3 id="usingdrupal">Using Drupal</H3></DT>
             <DL>
                    ...
              </DL>
<DT><H3 id="configuringdrupal">Configuring Drupal</H3></DT>
<DT><H3 id="troubleshooting">Troubleshooting</H3></DT>
<DT><H3 id="irc">IRC</H3></DT>
<DT><H3 id="themedev">Theme Development</H3></DT>
<DT><H3 id="dev4drupal">Developing for Drupal</H3></DT>
<DT><H3 id="licensing">Licensing and Trademark</H3></DT>
<DT><H3 id="drupalorg">Drupal.org</H3></DT>
</DL>

but this makes the HTML file look really messed up because of the length of text. Any suggestions ? Do I just use a single DL for answers, instead of nested DL, like

<H3 id="about">About Drupal</H3>
<DL> 
<DT>Q1</DT>
<DD>A1</DD>
<DT>Q2</DT>
          ...
</DL>
<H3 id="usingdrupal">Using Drupal</H3>
<DL>
          ...
</DL>
...
</DL>

This will make the HTML file / source code look really neat.

What would be better, in view of the long term maintainability that this document requires ?

1. Use XHTML lower-case tags
2. Nested is fine (IMO) and run it through htmltidy with 2-space indent (IMO). The raw code layout should not be your problem.

.. just my suggestions, others may have opinions

Thank you dman, all tags are now lowercase. I decided not to use nested dl's - it looks neater that way imo.
I'm submitting one more draft, this is almost feature complete (I hope !).
Things left now are:
- Feedback and suggestions from people ;)
- Change all http://drupal.org/xxx to /xxx (this was not done yet to facilitate people who view the FAQ on test sites)

Anything I have missed ?

Ouch, the last attachment had lots of whitespace / tab issues. All fixed now (I hope) thanks to aclight. Please review this version, and not the previous :)

A few nits:

1. "I would like to help the Drupal project by donating money." is not really a question. Same for "HELP! Sometimes when I load a URL on my site, I am presented with a blank white page. No contents. No errors. Nothing."

2. For "What license does Drupal use for its code?", you might mention the specific version of the GPL that Drupal uses and link to that.

I noticed a few other minor punctuation errors, etc. but it would take me longer to point out here than it would to edit the handbook pages at a later time, so I won't bother mentioning them.

Overall you are making great progress on this issue. I think you've gotten to the point where you're ready to start creating handbook pages on drupal.org and once that happens we should be able to give you credit for this.

Great job!

aclight, Ok I made those two into questions, and I've not mentioned that it's GPLv2.

keith.smith, " !" converted to "!" and same for question marks - I didn't know what was grammatically correct ;)
About the modules - as I was working through the list of factoids, I found many modules. As you had told me, I skipped them, but these 3 got through - akismet, autopilot, acidfree. I guess it's upto you to decide - should I remove those 3 and just keep CCK and views, or should I keep them.
IMO a better option would be to have a separate modules FAQ which will cover all the modules from the factoids.

Attaching yet another draft, this time I've cleaned up the internal links -- so it should be almost ready to be converted into a handbook, pending a decision over this modules issue.

I submitted the previous revision. It's here - http://drupal.org/node/202799
Seeing it on the site as a whole and not as an individual page, are there any aesthetic issues?
Any pending issues, apart from the inclusion of modules thing?

Thanks!

The handbook page looks really good and I don't see any outstanding issues, so I'm marking this fixed and giving rohan credit for a job well done. If anyone else notices any typos, etc. feel free to open this issue back up and rohan has told me he will fix them (or, if you have the appropriate privileges, just edit the handbook page yourself).

Great work!

Thank you very much, aclight, keith .. It was my pleasure :)