filing bugs for needed FAQ updates

[denise]

The perpetual bane of any product is making sure the documentation is up to date. We've been falling down on documentation for a while, and there are lots of reasons for that but I'd once again like to start trying to change it. Now that it's a new year, it's time to once again start in on a concerted effort to figure out what's missing from the FAQs (and then, of course, work to fix that, but the first step is identifying the scope of the problem!)

I have a few people working off the code tours to identify what we've added that needs to be documented, but consider this an open invitation to join them. If there's something you identify as missing from the FAQ, please open a bug for it (or if you don't want to navigate Bugzilla, you can just leave a comment here and someone will move it into Bugzilla for you).

See Bugzilla: How to enter, find and work on docs bugs for reference, and the list of open docs bugs to see what's already been reported.

Comments

Notifications

[insignia]

The FAQ says that "All notifications will automatically be sent to your inbox." However, some notifications are only sent to your e-mail address. Perhaps changing "all" to "most" would be a good idea, to avoid confusion.

Re: Notifications

[inoru_no_hoshi]

I noticed this - hunted down pertinent FAQ and filed a bug! Thank you. :D

[rike_tikki_tavi]

So I'd like to try and help. Found an easy bug to work on (actually the one reported above) and I have one question. Lots of the FAQs include links. Should we just ignore those when writing a new/revised FAQ text or what should we do?

[denise]

I'm not quite following you! If there's a link in the text and you think it should stay (most FAQs should be linked to other things; if you mention a page on the site, for instance, the page title should be a link to the page, that kind of thing) you should leave it there. (The ideal idea is that I should be able to just copy/paste the FAQ from Bugzilla into the FAQ editor.) If you don't know how to make a link I can show you!

(PS: yay and thank you for wanting to help! if you want to contribute docs, we'll need you to sign a contributor licensing agreement (it's the attachment on that bug) -- that's to make sure we can legally relicense your contributions (since the FAQs are released under a Creative Commons license) and it protects you because it explicitly says you keep all other rights to your contributions and aren't expected to keep providing support for them in the future.)

[rike_tikki_tavi]

Ok, I explained that badly. In the FAQ I want to amend is a link to the FAQ for the inbox. But since I thought we should write our docs as txt files I'm not sure how to incorporate the link. Should I write the html for the link in brackets behind the word that will be the link or is there another rule for this?

Re the CLA, I've already downloaded the pdf but I'll have to wait till Monday to get it to you. I'll have to print and scan it at work since I don't have a printer/scanner at home.

[denise]

You should be uploading as .txt files, yeah, but you can just write the HTML directly in there. Like, if you wanted to link to the inbox in a sentence like "You can find notifications in your Inbox", put it in the file like:

You can find notifications in your <a href="http://www.dreamwidth.org/inbox">Inbox</a>.

Even if you're saving the file as .txt you can still put the HTML markup in it.

[rike_tikki_tavi]

That's exactly what I wanted to know. Thanks for your fast answer.

[denise]

You're welcome!

[adannu]

Ooh. I've been thinking about volunteering for this and was wondering how/where to get started so yay. :D