Improvements in contributing to docs
- dakur
- Member | 493
Quite often, if something is wrong in docs, you can read “can you make a PR?”. Yes, I can, but I'm struggling with editing docs so I have few questions/suggestions:
- Is there a design guide? I'd like to improve docs but I don't want to give my time on searching patterns in already existing texts. I'd like to have clearly stated “there are these types of formatting and you can use them in this way” For example I've suggested this component in another topic which I think I saw somewhere in nette docs, but I have no clue how to achieve it or what are the alternatives/possibilities.
- Couldn't we use Markdown? I don't want to struggle with another markup language which is actually so similar to markdown that you make mistakes easily. The industry-standard is markdown and there are plenty of tools for it – from integration in PhpStorm to native rendering in github/gitlab or wysiwyg editor Typora. It's much easier to concentrate on content with these tools and it saves time & energy.
- Is it possible to transfer creation of docs to some visual tool like Notion? Now, to edit docs, you have to update fork (which basically means to delete it and fork again) and open PhpStorm which is quite inconvenient.
- David Grudl
- Nette Core | 8228
There's some description of the formatting at https://doc.nette.org/…uting/syntax, including the boxes. For previews can be used https://editor.nette.org/.
Markdown is used there, or what exactly are you missing? The file extension is texy, but it doesn't matter, I also have PhpStorm set to treat *.texy as Markdown.
I don't know Notion and I don't know what advantages it brings, but such a transition would involve a huge amount of work, which I don't feel like doing.
