Current efforts

jordanjay29

@Arkinn, let's use this discussion to track the current doc efforts. We can start by laying out what we've discussed so far in Gitter chat.

Finishing the rest of the documentation port to the new docs format.
Establish a standard documentation style following some of the ideas you had, listed below:
1. Use Capital Letters, Bold, Italics and a code background to highlight key words in important instructions.
2. Add either Images, Animated pictures, or Videos to the documentation to help provide some visual support.
3. Add formatted links to the bottom of the Installation docs
Expand the current docs with the additional suggestions you had to improve them:
1. Install guides for the dependencies, like PHP, MySQL, Apache/Nginx to avoid misconfigured servers
2. A comprehensive how-to guide for using Flarum
3. A guide for moving Flarum to another folder

That sounds like a good list to tackle at the start. I'd suggest starting at the top with the rest of the current docs to the new format, then they can be submitted to the Flarum/docs repo as a pull request. We can start thinking on the new guides after that.

And we can open a new discussion topic here if we want to explore documentation formatting in more depth.

How does that sound?

Arkinn

That sounds good to me.

So for the time being, I'll concentrate on finishing the port, putting the formatting into place, and getting the screenshots up into the guides. Once that's done I'll let you know, then we can as you say start to work on the new guides.

luceos

Good to see you're picking this up! It's much appreciated ?

Arkinn

@luceos

You're welcome. ?

@jordanjay29

Apart from one page, and a couple of sections where there's no structure I've completed the Port, and added all the default formatting in the original (plus some of my own). The single page left out I intend to put where the README.md is as it's an index to the documentation.
Translating - there is nowhere for that on the new structure, so that too I left out. I will add it when we have the structure for it.

You mentioned earlier about creating a new discussion topic about exploring the document formatting so that's creating a standard for it, I have a few things I'd like to propose on that end, so should I go ahead and create said conversation?

jordanjay29

Arkinn Yes, you should have the ability to make new discussions in here, so you can use it as you see fit.

Good job (and quick work, wow) on the porting.

jordanjay29

As we're porting these, we should update these docs. A few things jumped out at me:

FAQ:
Adding a header/logo This is now a feature included in Flarum. Can you come up with some wording to better reflect this and add it?
Translating Flarum We actually have these docs, I think they got missed in the port (they should go here) and we should link them in this FAQ.

It looks like our structure lacks places for the Adding Languages doc, where do you think this fits best? Under /user/? Maybe add a languages.md file (if you don't know how to do this via git, you can do it on Github directly).

Once we have this done, go ahead and create a pull request on the official docs repository so we can our progress so far merged in.

Arkinn

Header/Logo
I can do that, I am also looking to add this in as a part of the user manual too so eventually, that would be a link to the page when it's created. But for now, I could just write a short tutorial on how that needs to be done? sound good to you?

Translations
Yes it was left out because I didn't see an appropriate place for it to go, I.E. no section for translations, but as you've pointed that out I've ported it over just now. (literally just finished it), and added the link in the FAQ.

Adding Languages
I think that would be a good place to put it, also for the admin section of the user manual?

jordanjay29

Arkinn You don't have to wait for me to approve how you implement things, just go ahead and we can talk about how to make it better later. If you have a better idea for how to do things, too, throw them out and work on them if you like (you can always branch your repo to give yourself some space to play and try out new things). We can measure how they look against the current spec and see if that's the best course of action or not.

Arkinn

@jordanjay29
Good to know, thanks.
I wrote a small tutorial in the FAQ on uploading logos, etc.
Also added the file for languages in the user/ directory, and ported it over. A link to that is also in the index.md under the optional sub-heading.

As the above are completed, I've submitted a pull request.

jordanjay29

I split the other into it's own so we can keep using this for tracking.

Your PR is merged, btw.