"These days our documentation is actually quite thorough, and the FAQ could probably leverage it better. For instance, it could give a brief answer and a couple hints for the most common things people want to do, and then "For more detailed information about customizing Inkscape, please see the <link>Customizing Inkscape</link> chapter of the Inkscape Manual" (or whatever)."
As I suspected, there are indeed a lot of user-related pages in the wiki. For this page: http://wiki.inkscape.org/wiki/index.php/Customizing_Inkscape, Bryce suggested: "I think it's a bit too much for the FAQ. The contents of that wiki page looks like it really ought to be part of some official documentation, like the man page or something."
Now I just ran into this page: http://wiki.inkscape.org/wiki/index.php/LaTeX (which is linked to faq item 2.5). I suppose this should be part of "some official documentation" as well. But documentation, in general, is a part of Inkscape that I'm not so familiar with.
Really, the only documentation I know about, is the manual, the official tutorials, and the wiki (aside from Launchpad and Sourceforge docs). So my next question, is how to handle items which need to be added to "some official documentation". Is there a particular person who is in charge of documentation? I could make a list and give to this person. But then my work can't get finished, until their work is finished. Well, then maybe I should handle it myself? But I would need a bit of guidance. I certainly can copy/paste, and write some html. It's just where to put it, that I'm not sure.
Maybe I could make a new page (at first on staging site, of course)? I would just transfer all wiki content which is currently used to answer user questions in the faq, to this page, and link to the info there.
However, I suspect Bryce had something else in mind with "some official documentation".
How should I handle this kind of documentation?
Thanks again, brynn
-------------------------------------------------- From: "Bryce Harrington" <bryce@...961...> Sent: Sunday, August 17, 2014 12:56 PM To: "Brynn" <brynn@...3133...> Cc: "Inkscape-Devel" Inkscape-devel@lists.sourceforge.net Subject: Re: [Inkscape-devel] splitting FAQ in 2
On Sun, Aug 17, 2014 at 01:48:24AM -0600, Brynn wrote:
Thanks Bryce.
"> Similarly, if you follow the user list or the #inkscape user channel and
see questions being asked a lot (and that sound likely to continue being asked long in the future), consider adding Q&A's for those."
I recently subscribed to the user list, but I didn't even know about #inkscape user channel. That's an IRC channel...or....that's not twitter, is it? (Sorry, I don't participate in the whole social media thing.) However, I'm quite familiar with messages posted in forums, and somewhat with messages posted in Launchpad Answers.
Yes, it's an IRC channel. For more info see the end of this page:
Fwiw, the Jabber info on that page is all obsolete I think.
I'll make a list of the bad links (dead, empty, not found pages) (which I guess is what you mean by "bitrot"), and send them to you. Maybe you can find them somewhere.
Yes, that's what bitrot means.
FWI, I'm on travel this coming week so might not be very responsive in the near term, but will catch up once I'm back.
We also have an #inkscape-devel channel, which you're welcome to join as well. su_v is very active there and she might be able to help if I'm not around.
Speaking of a listing of tutorials -- would those be only "official" tutorials? Or should all kinds of outside tutorials (such as listed on my webpage) be found on the Tutorials page? Already, there are lots of tutorials from a deviantART feed that Martin set up (which are "outside" tutorials). But with such a listing of outside tutorials, again, you'll have the bitrot issue, and possible frequent requests to be listed.
The FAQ probably should only directly link to the official tutorials (the ones that appear in-program). Those are the ones we have direct control over and can prevent bitrotting.
I'd love to see more work go into the Tutorials section, but don't have specific advice. The Tutorials page doesn't need to be limited to official tutorials. I like how Martin set it up to pull from deviantArt because then we don't have to worry about bad links on our end.
"Our
software documentation is also a lot better than when this FAQ was initially written, too."
and regarding the Customizing Inkscape faq item "> There might be a few other FAQ items like this, that should just move to
proper docs."
and "Also I think it probably isn't that
'frequent' of a question so once it's in the program documentation it can be dropped from the FAQ."
Are you suggesting that if documentation for an faq item exists, that it should be deleted from the faq? Or that the answer should be deleted, and instead should link to the documentation?
Because I think a lot of people, maybe even most people, think of an FAQ for just exactly that "frequently asked questions". Perhaps the faq has been used in the past, as a place for developers to put answers, and for users to find answers, when no other documentation exists. But I'm not sure taking it completely out of the faq would be appropriate, if it truly is asked for frequently. For customizing Inkscape, I can say that it is asked surprisingly often! I've even heard people say they won't use Inkscape unless they can have a customized theme! (Of course, imo, that's their problem, but it is a fairly common topic.) (And btw, easily customizable themes, or "skins", is a much wished-for feature!)
Yes, I completely agree with all of this. It's true that in the far past we did put stuff in the FAQ that should have just gone into regular docs but we didn't have those at the time. Since then I think a lot of that has been scrubbed out. I just want to suggest that if you feel there is stuff in there that's a bit too much for the FAQ, then moving it into proper documentation is the right way to go.
These days our documentation is actually quite thorough, and the FAQ could probably leverage it better. For instance, it could give a brief answer and a couple hints for the most common things people want to do, and then "For more detailed information about customizing Inkscape, please see the <link>Customizing Inkscape</link> chapter of the Inkscape Manual" (or whatever).
Bryce