Clarify information about contributing to the docs

[sypets]

From @nearlythere, moved from #45

I don't know what the plan is for a homepage, but I am trying to wrap my head around docs for an article, and found myself feeling like it's fractured, dispersed, and duplicated in some places. If there was a central homepage to collect the main info, it would be awesome.

As a newcomer to contributing to documentation, I want to know:

• [x] “Where the action is” - what is happening right now, what help they need.
• [ ] Is there a roadmap of where help is needed right now?
• [ ] To find out contribution guidelines, I don’t want to step on toes or do things wrong, piss people off.
• [x] In general, what kinds of contributions are welcome, or unwelcome?
• [ ] How it all works, how it’s all organized.

These are the various links I found helpful, but wondered what was the difference in some cases.

• [ ] What is it all about, is this up to date? (no dates, no signs of life or activity) https://typo3.org/help/documentation/

• [x] Who is behind it (no signs of life/activity?) https://typo3.org/community/teams/documentation/

• [ ] How it all works? Is this everything? https://github.com/TYPO3-Documentation

Contribution guide?

• [x] What about this https://docs.typo3.org/Contribute/Index.html versus https://docs.typo3.org/typo3cms/HowToDocument/WritingDocsOfficial/Index.html#docs-contribute

• [x] Where’s the action? This is great! https://docs.typo3.org/News/2018/Index.html versus things like team meeting notes - is this the same? https://forge.typo3.org/projects/team-docteam/wiki/index

[sypets]

Moved from #45

@nearlythere Welcome!

I think @marble should answer most of this, but a few answers from me:

• Contribution: I'm kind of responsible for the 2 places. https://docs.typo3.org/Contribute/Index.html is a short intro, https://docs.typo3.org/typo3cms/HowToDocument now contains everything you should need for writing docs, including the chapter on contributing to the official docs. We thought about a "Contribution guide" for the docs or a general contribution guide for TYPO3, but there is a lot of overlap with general writing docs stuff which is not specific to contribution (e.g. for documenting your own extension). I'm pretty confident this is the best solution right now, but feel free to suggest changes. To sum it up: use https://docs.typo3.org/typo3cms/HowToDocument as compendium, if you want to jump in write away without reading tons of stuff, use "edit me on github" (on any page of the docs in the top right) or look at tutorial: https://www.youtube.com/watch?v=wNxO-aXY5Yw

Duplicate text in different places is also a big annoyance for me, so shame on me for being responsible, but sometimes you add new stuff and don't want to remove the old stuff just yet.

My personal advice from my experience: Just start. You don't have to worry too much about doing stuff wrong. You will learn as you go along. Start with small patches. Any change (Github Pull Request) you create will not be visible immediately, it needs to be merged by experienced maintainers. They will give feedback. Don't worry. Just don't start with a huge change. Start small.

For communication in general, I would recommend joing the Slack channel: Get a typo3.org account, then get a slack account. Join #typo3-documenation. There, you can also ask questions.

• get a typo3.org account: see https://docs.typo3.org/typo3cms/ContributionWorkflowGuide/Account/TYPO3Account.html
• get a slack account: see https://docs.typo3.org/typo3cms/HowToDocument/HowToGetHelp.html
• join #typo3-documentation channel on slack: https://typo3.slack.com
• get a Github account. Well, you already have that, obviously!

P.S. There is also a monthly Slack call. You will find out about that, when you joined the Slack channel.

Happy contributing!

[sypets]

Moved from #45

Oh, about where you can help. See https://docs.typo3.org/typo3cms/HowToDocument/WritingDocsOfficial/HowYouCanHelp.html

But in my experience, people tend to find the job they want to do themselves and that is not a bad thing: What hurts you most, what bothers you, where do you see a need for improvement? Get started on that. Don't just write issues, make the changes you find useful yourself, as a pull request. Wait for the reaction. Improve your patch. Ask questions in the Slack #typo3-documenation channel. Again: start small.

[sypets]

Moved from #45 (@nearlythere):

@sypets Ah thank you! That is super helpful, and I will add that info into the article I was researching.

I was responding to this task as "a home page" design, and what I - as a newcomer - was looking for.

So, my questions were rhetorical, rather than actual, if you get me!

But thank you thank you for that, because i can incorporate it into the article.

[sypets]

We handled most of the issues raised. I would like to close now.

“Where the action is” - what is happening right now, what help they need. Is there a roadmap of where help is needed right now?

see for example:

• what help is needed: https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingDocsOfficial/HowYouCanHelp.html
• roadmap: https://typo3.org/community/teams/documentation/

To find out contribution guidelines, I don’t want to step on toes or do things wrong, piss people off. In general, what kinds of contributions are welcome, or unwelcome?

The "How you can help" page could be clarified more, if required.

How it all works, how it’s all organized.

• see Contribution workflow: https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingDocsOfficial/Index.html

more about task forces, etc. is to come.

These are the various links I found helpful, but wondered what was the difference in some cases. What is it all about, is this up to date? (no dates, no signs of life or activity) https://typo3.org/help/documentation/

We should determine what should be the start page / landing page for the documentation.

See also #45: There was also the idea of using a TYPO3 instance with t3o layout for the docs.typo3.org start page.

Who is behind it (no signs of life/activity?) https://typo3.org/community/teams/documentation/

True. Has now been updated and news plugin added to show latest team news on of typo3.org

How it all works? Is this everything? https://github.com/TYPO3-Documentation

Contribution guide?

There is already a contrib guide for core development. Because we already had "Writing Documentation", which is quite extensive and already contained most of the information for contributors, we just added a dedicated menu entry for contributors there: https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingDocsOfficial/Index.html

What about this https://docs.typo3.org/Contribute/Index.html versus https://docs.typo3.org/typo3cms/HowToDocument/WritingDocsOfficial/Index.html#docs-contribute

now the first redirects to the latter.

Where’s the action? This is great! https://docs.typo3.org/News/2018/Index.html versus things like team meeting notes - is this the same? https://forge.typo3.org/projects/team-docteam/wiki/index

The forge wiki ist maybe not ideal, but that is what is commonly being used. Unless something better is found, we use the forge wiki.

The wiki has now been cleaned up and reduced to a stub. We direct people to typo3.org for the team page and "Writing documentation" for contribution.