Add a How-To section

[ohmeow]

Would be nice to have an ever-growing how-to section added to the repo. I'm familiar with jekyll but strugging to, for example, find out how to change the header of the page so I can replace my domain name with an image.

Other examples may include:

• How to add your own favicon
• How to make your blog width 100% ...

[natikgadzhi]

I think as we get more and more questions here, on the forums, and on Twitter, @hamelsmu and I can group the most popular ones into sections of the readme.md and development.md.

Do let us know if you won't be able to figure anything out, we'll try to help you. I think the easiest way though would be through the forum thread.

[hamelsmu]

It is possible that we should host a docs site (will have to be in a seperate repo), only because too many markdown files etc. will become hard to read / search?

Thoughts?

[natikgadzhi]

If we rebuild fastpages as in nbdev — we'd have the docs site for free.

Upd: we don't actually have to publish it to pypi and distribute with pip if we move towards nbdev approach. We can just build the library with nbdev, and tell it to, say, put lib files into _action_files, and docs to a separate folder. We then figure out a way to incorporate docs into fastpages.fast.ai, without compromising on the blog sections, and viola.

Upd 2: sorry for jumping so out of scope of the original question. I agree, @hamelsmu, managing 3 md files is a headache, managing 4 (+FAQ) is worse. Question is, is it cheaper than building a separate docs site / moving to nbdev approach, or is it ok for now ;)

[hamelsmu]

If we rebuild fastpages as in nbdev — we'd have the docs site for free.

☝️ Unfortunately we would not be able to host it on github pages, because that real estate is already occupied on this repo for https://fastpages.fast.ai/, so we would have to use a different repo

Not sure nbdev is the best way to generate a docs site for fastpages, when the repo is substantially non-python (Actions, Docker, CSS, HTML) and is a collection of documents rather than a library? Could be adding too much uncessary overhead with no benefit? I could be wrong

[hamelsmu]

Another solution to a How-To guide that is crowdsourced from the community that I discussed with @jph00 is to invite people to contribute blog posts to this page. It sounds like a good idea, but I suppose we would have to create some rules, etc. to make the process more transparent and set expectations.

If anyone has any thoughts let me know

[jph00]

I think it's mainly a matter of expectations. For contributions to fast.ai sites, we generally tell people to write stuff to host elsewhere, and then if they'd like it as, say a PR to some fast.ai project, submit it--but we can't promise to accept it in any form, and even if we do accept the idea we might well rewrite it. If we think what you've written is relevant and interesting and appropriate for us to include, then we will try to help you bring it up to a "fast.ai-worthy" level and make it fit with the rest of our pages and tools.

Most people don't follow through, and don't maintain their initial enthusiasm, so this avoids us wasting time on ideas that don't really go anywhere, but does allow tenacious and committed people to get involved.

[natikgadzhi]

Another solution to a How-To guide that is crowdsourced from the community that I discussed with @jph00 is to invite people to contribute blog posts to this page. It sounds like a good idea, but I suppose we would have to create some rules, etc. to make the process more transparent and set expectations.

After sitting on this for a day, I believe I was wrong about how good it would be to just port it to nbdev, too excited about the idea. I think you're right that there's a ton of non-python infra that is core to the project.

Crowdsourcing posts on fastpages repo itself and posting them to fastpages.fast.ai is a brilliant idea that I, to my embarasment, haven't thought about. 👏

[hamelsmu]

@ohmeow closing this, but feel free to write something up after you have collected some how-tos or tips.

Also feel free to start a fastai forum thread on how tos if you don't want to be as formal as writing a blog post (but we encourage you to write one if you can)